headroomlabs-ai/headroom · error · ImportError

litellm is required for LiteLLMBackend. Install with: pip in

Error message

litellm is required for LiteLLMBackend. Install with: pip install litellm

What it means

LiteLLMBackend.__init__ raises ImportError when the optional litellm package is absent (LITELLM_AVAILABLE falsy). Like the other backend guards, it fails at construction time with the exact pip command, rather than at first request.

Source

Thrown at headroom/backends/litellm.py:614

    def __init__(
        self,
        provider: str = "bedrock",
        region: str | None = None,
        profile_name: str | None = None,
        **kwargs: Any,
    ):
        """Initialize LiteLLM backend.

        Args:
            provider: LiteLLM provider prefix (bedrock, vertex_ai, openrouter, etc.)
            region: Cloud region (provider-specific)
            profile_name: AWS named profile for credential resolution (bedrock only).
                          When set, boto3 uses this profile (e.g. an SSO profile) instead
                          of the ambient credentials. Ignored for non-bedrock providers.
            **kwargs: Additional provider-specific config
        """
        if not LITELLM_AVAILABLE:
            raise ImportError(
                "litellm is required for LiteLLMBackend. Install with: pip install litellm"
            )

        self.provider = provider
        self.region = region
        self.profile_name = profile_name
        self.kwargs = kwargs

        # Get provider config from registry
        self._config = get_provider_config(provider)

        # For Bedrock, fetch model map dynamically from AWS API
        if provider == "bedrock":
            # litellm takes the botocore-backed `_auth_with_aws_session_token`
            # path as soon as temporary credentials (AWS_SESSION_TOKEN) are
            # present. botocore is an optional dependency (the `bedrock`
            # extra); when it is absent — as in the slim default Docker image —
            # the failure only surfaces at request time as a misleading

View on GitHub (pinned to 322425c43b)

Solutions

pip install litellm (or add the appropriate headroom extra that pulls it in).
Rebuild the Docker image with litellm included if you selected the litellm backend in config.
Verify with python -c "import litellm" before wiring the backend into startup.

Example fix

# before
backend = LiteLLMBackend(provider="openrouter")  # ImportError

# after
# pip install litellm
backend = LiteLLMBackend(provider="openrouter")

Defensive patterns

Strategy: validation

Validate before calling

def litellm_available() -> bool:
    try:
        import litellm  # noqa: F401
        return True
    except ImportError:
        return False

assert litellm_available(), "LiteLLMBackend requires: pip install litellm"

Try / catch

try:
    backend = LiteLLMBackend(provider="openrouter")
except ImportError as e:
    raise SystemExit(f"{e}; rebuild the image with litellm installed") from e

Prevention

Include litellm in the deployment whenever the litellm backend is selected in config.
Fail at process start, not first request: construct backends eagerly during startup.
Keep slim images and optional deps in sync via per-backend extras in requirements.

When it happens

Trigger: Instantiating LiteLLMBackend(provider='bedrock'|'vertex_ai'|'openrouter'|..., ...) without litellm installed in the environment.

Common situations: Running the slim default Docker image, which omits provider SDKs; installing headroom-ai without the litellm extra; a dependency resolver dropping litellm after a conflict.

Related errors

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