NousResearch/hermes-agent · error · RuntimeError

Voice mode requires sounddevice and numpy. Install with: {sy

Error message

Voice mode requires sounddevice and numpy.
Install with: {sys.executable} -m pip install sounddevice numpy

What it means

Raised when voice recording starts on a non-Termux platform and check_voice_requirements() reports audio unavailable — i.e. the Python 'sounddevice' and/or 'numpy' packages needed for microphone capture are missing or unimportable. The message embeds the current interpreter path so the pip install targets the right environment.

Source

Thrown at cli.py:12900

            return
        from tools.voice_mode import create_audio_recorder, check_voice_requirements

        reqs = check_voice_requirements()
        if not reqs["audio_available"]:
            if _is_termux_environment():
                details = reqs.get("details", "")
                if "Termux:API Android app is not installed" in details:
                    raise RuntimeError(
                        "Termux:API command package detected, but the Android app is missing.\n"
                        "Install/update the Termux:API Android app, then retry /voice on.\n"
                        "Fallback: pkg install python-numpy portaudio && python -m pip install sounddevice"
                    )
                raise RuntimeError(
                    "Voice mode requires either Termux:API microphone access or Python audio libraries.\n"
                    "Option 1: pkg install termux-api and install the Termux:API Android app\n"
                    "Option 2: pkg install python-numpy portaudio && python -m pip install sounddevice"
                )
            raise RuntimeError(
                "Voice mode requires sounddevice and numpy.\n"
                f"Install with: {sys.executable} -m pip install sounddevice numpy"
            )
        if not reqs.get("stt_available", reqs.get("stt_key_set")):
            raise RuntimeError(
                "Voice mode requires an STT provider for transcription.\n"
                "Option 1: uv pip install faster-whisper  "
                "(free, local; `pip install faster-whisper` also works if pip is on PATH)\n"
                "Option 2: Set GROQ_API_KEY (free tier)\n"
                "Option 3: Set VOICE_TOOLS_OPENAI_KEY (paid)"
            )

        # Prevent double-start from concurrent threads (atomic check-and-set)
        with self._voice_lock:
            if self._voice_recording:
                return
            self._voice_recording = True

View on GitHub (pinned to c896c09c42)

Solutions

Install into the SAME interpreter shown in the message: `<that python> -m pip install sounddevice numpy`
If import still fails, install the system portaudio library (apt install libportaudio2 / brew install portaudio)
Verify with `python -c "import sounddevice, numpy"` before retrying `/voice on`

Example fix

# before
/voice on  # RuntimeError: Voice mode requires sounddevice and numpy.

# after
source .venv/bin/activate
python -m pip install sounddevice numpy
/voice on

Defensive patterns

Strategy: validation

Validate before calling

import importlib.util, sys

def audio_deps_available() -> bool:
    return importlib.util.find_spec("sounddevice") is not None and \
           importlib.util.find_spec("numpy") is not None

if not audio_deps_available():
    print(f"{sys.executable} -m pip install sounddevice numpy")

Try / catch

try:
    cli._voice_start_recording()
except RuntimeError as e:
    if "sounddevice and numpy" in str(e):
        subprocess.run([sys.executable, "-m", "pip", "install", "sounddevice", "numpy"])
    else:
        raise

Prevention

Install sounddevice/numpy into the same venv that runs Hermes
Check `import sounddevice` succeeds — a missing system portaudio fails the import even with the wheel installed
Run the interpreter-qualified install command printed in the error, not bare pip

When it happens

Trigger: Running `/voice on` on desktop Linux/macOS/Windows where sounddevice or numpy is not installed, or is installed into a different Python than the one running Hermes (e.g. system pip vs .venv).

Common situations: Fresh install without the optional audio extras; installing with pip while running under a venv (or vice versa); a broken portaudio system library making `import sounddevice` fail even though the wheel is present.

Related errors

AI-assisted analysis of NousResearch/hermes-agent@c896c09c42 (2026-08-14). Data as JSON: /api/errors/8244299cf8ded0ba. Report an issue: GitHub.