headroomlabs-ai/headroom · error · ImportError

FastAPI required. Install: pip install fastapi uvicorn httpx

Error message

FastAPI required. Install: pip install fastapi uvicorn httpx

What it means

create_app raises ImportError when the optional FastAPI stack is not installed. The server module imports guardedly so library/tests can import it without FastAPI, but constructing the app requires fastapi, uvicorn, and httpx. The message names the exact pip extras needed.

Source

Thrown at headroom/proxy/server.py:2465

    """Normalize project-prefixed WebSocket paths before route matching."""

    def __init__(self, app: Any) -> None:
        self.app = app

    async def __call__(self, scope: Any, receive: Any, send: Any) -> None:
        if scope["type"] == "websocket":
            prefix_project = strip_project_path_prefix(scope)
            headers = {
                name.decode("latin-1"): value.decode("latin-1") for name, value in scope["headers"]
            }
            set_current_project(classify_project(headers) or prefix_project)
        await self.app(scope, receive, send)


def create_app(config: ProxyConfig | None = None) -> FastAPI:
    """Create FastAPI application."""
    if not FASTAPI_AVAILABLE:
        raise ImportError("FastAPI required. Install: pip install fastapi uvicorn httpx")

    from headroom.proxy.forwarded_headers import load_trusted_dashboard_client_cidrs

    # Parse once at startup so invalid operator configuration fails loudly.
    trusted_dashboard_client_cidrs = load_trusted_dashboard_client_cidrs()

    from contextlib import asynccontextmanager

    # Always-on file logging to ~/.headroom/logs/ for `headroom perf` analysis.
    # Installed here (not at module import) so importing headroom.proxy.server
    # in tests or library contexts does not silently attach a RotatingFileHandler
    # to the user's live proxy.log.
    _setup_file_logging()

    config = config or ProxyConfig()

    # Defensive re-apply of file-backed settings for embedded/non-CLI callers
    # that construct the app without going through the `headroom` CLI entrypoint

View on GitHub (pinned to 322425c43b)

Solutions

1. Install extras: pip install fastapi uvicorn httpx.
2. Prefer the documented server/proxy extras command from the project README if provided.
3. In library-only code paths, avoid calling create_app/run_server; import specific modules instead.

Example fix

# before
app = create_app()  # ImportError

# after
# pip install fastapi uvicorn httpx
app = create_app()

def fastapi_available() -> bool:
    try:
        import fastapi, uvicorn, httpx  # noqa: F401
        return True
    except ImportError:
        return False

try:
    app = create_app(config)
except ImportError as e:
    if "FastAPI required" in str(e):
        sys.exit("Install server extras: pip install fastapi uvicorn httpx")
    raise

When it happens

Trigger: Calling create_app() in an environment where the fastapi/uvicorn/httpx optional group is missing, e.g. minimal install for SDK-only usage, or calling run_server/create_app in a test venv without server extras.

Common situations: Installing headroom-core without the proxy/server extra; stale venvs after adding the dependency group; CI job reusing a cached environment.

Related errors

• sentence-transformers is required for LocalEmbedder. Install
• openai is required for OpenAIEmbedder. Install it with: pip
• httpx is required for OllamaEmbedder. Install it with: pip i
• any-llm-sdk is required for AnyLLMBackend. Install with: pip
• litellm is required for LiteLLMBackend. Install with: pip in

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