headroomlabs-ai/headroom · error · SystemExit

Error: Proxy dependencies not installed. Run: pip install he

Error message

Error: Proxy dependencies not installed. Run: pip install headroom-ai[proxy]

What it means

`headroom proxy` builds a list of required modules (uvicorn/fastapi + orjson etc. depending on options) and imports each before starting. Any ImportError triggers the red 'Proxy dependencies not installed. Run: pip install headroom-ai[proxy]' message (with the failing module in Details:) and exit 1. The proxy is an optional heavyweight component, so its deps are not in the base install.

Source

Thrown at headroom/cli/proxy.py:51

        "websockets",
        "onnxruntime",
        "transformers",
        "watchdog",
    ]
    if sys.implementation.name != "pypy":
        required_modules.append("orjson")

    try:
        for module in required_modules:
            import_module(module)
    except ImportError as e:
        click.secho(
            "Error: Proxy dependencies not installed. Run: pip install headroom-ai[proxy]",
            fg="red",
            err=True,
        )
        click.secho(f"Details: {e}", fg="red", err=True)
        raise SystemExit(1) from None


# ---------------------------------------------------------------------------
# Startup log suppression.
#
# sentence_transformers makes HEAD/GET requests to HuggingFace Hub on every
# worker startup to validate the model manifest.  Each request produces an
# INFO-level httpx record and a WARNING from huggingface_hub about a missing
# HF_TOKEN.  With 8 workers this generates ~50 noisy lines per startup.
#
# Placing the suppression here (module-level in the first CLI module imported)
# ensures it is in place before sentence_transformers, huggingface_hub, or
# httpx are initialised by any downstream import or worker fork.
#
# The env vars silence the warnings.warn() path ("unauthenticated requests"
# message) which bypasses the logging system entirely.
# ---------------------------------------------------------------------------

View on GitHub (pinned to 322425c43b)

Solutions

pip install 'headroom-ai[proxy]'
Match the Details: module — if orjson is named and you triggered the fast-json option, either install orjson or drop the flag
For deployments, bake the extra into the image: pip install 'headroom-ai[proxy,mcp]' as needed
Verify all required modules in one shot: python -c "import uvicorn, fastapi, orjson"

Example fix

# before
$ headroom proxy start
# Error: Proxy dependencies not installed. Run: pip install headroom-ai[proxy]

# after
$ pip install 'headroom-ai[proxy]'
$ headroom proxy start

Defensive patterns

Strategy: validation

Validate before calling

required = ["uvicorn", "fastapi"] + (["orjson"] if fast_json else [])
missing = [m for m in required if importlib.util.find_spec(m) is None]
if missing:
    raise SystemExit(f"missing proxy deps {missing} — pip install 'headroom-ai[proxy]'")

Try / catch

try:
    import_module("uvicorn")
except ImportError as e:
    raise SystemExit(f"proxy extra missing: {e}") from None

Prevention

Install 'headroom-ai[proxy]' wherever the proxy runs, including containers
If you toggle fast-json options, ensure orjson is present or don't enable them
Prefer find_spec() checks over bare imports in multi-worker setups to avoid partial initialization

When it happens

Trigger: Running `headroom proxy ...` where uvicorn, fastapi, orjson, or another listed module is missing — e.g. bare install, or enabling an option that appends 'orjson' to required_modules without it installed.

Common situations: pip install headroom-ai without [proxy]; Docker images slimmed aggressively; option flags (e.g. fast-json paths) that require orjson but environment only has stdlib json.

Related errors

AI-assisted analysis of headroomlabs-ai/headroom@322425c43b (2026-08-15). Data as JSON: /api/errors/cb2731f04e3e9fe2. Report an issue: GitHub.