headroomlabs-ai/headroom · error · ImportError

httpx is required for OllamaEmbedder. Install it with: pip i

Error message

httpx is required for OllamaEmbedder. Install it with: pip install httpx

What it means

OllamaEmbedder._check_dependencies probes for the httpx package during __init__ and raises this ImportError (chaining the original) when missing. httpx is the HTTP client used for the async /api/embed calls against a local Ollama server; it is an optional dependency from headroom's perspective, so environments without it fail here at construction time, not mid-request.

Source

Thrown at headroom/memory/adapters/embedders.py:869

        Raises:
            ImportError: If httpx library is not installed.
        """
        self._check_dependencies()

        self._model_name = model_name or self.DEFAULT_MODEL
        self._base_url = (base_url or self.DEFAULT_BASE_URL).rstrip("/")
        self._max_retries = max_retries if max_retries is not None else self.MAX_RETRIES
        self._explicit_dimension = dimension
        self._detected_dimension: int | None = None
        self._client: Any = None  # httpx.AsyncClient when initialized
        self._lock = asyncio.Lock()

    def _check_dependencies(self) -> None:
        """Check that required dependencies are installed."""
        try:
            import httpx  # noqa: F401
        except ImportError as e:
            raise ImportError(
                "httpx is required for OllamaEmbedder. Install it with: pip install httpx"
            ) from e

    async def _get_client(self) -> Any:
        """Get or create the httpx async client."""
        if self._client is None:
            import httpx

            self._client = httpx.AsyncClient(
                base_url=self._base_url,
                timeout=self.REQUEST_TIMEOUT,
            )
        return self._client

    async def _embed_single_with_retry(self, text: str) -> np.ndarray:
        """Call Ollama API with retry logic for a single text.

        Args:

View on GitHub (pinned to 322425c43b)

Solutions

1. pip install httpx in the active interpreter.
2. Install headroom with the embeddings/local extras so httpx is pulled in by default.
3. Verify interpreter alignment: python -m pip install httpx using the same python that runs your app.
4. If httpx cannot be installed, use LocalEmbedder (sentence-transformers) instead.

Example fix

# before
emb = OllamaEmbedder()  # ImportError: httpx is required

# after (shell)
pip install httpx
emb = OllamaEmbedder()

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

if not ollama_deps_available():
    raise SystemExit("pip install httpx before using OllamaEmbedder")

try:
    emb = OllamaEmbedder()
except ImportError as e:
    if "httpx" in str(e):
        raise SystemExit("pip install httpx to use OllamaEmbedder") from e
    raise

When it happens

Trigger: Constructing OllamaEmbedder() (e.g. via the memory factory or config selecting the ollama embedder) in an environment where httpx isn't installed — slim containers, minimal CI, or a fresh venv without extras.

Common situations: Docker images built for the OpenAI path that later switch embedder config to ollama; dependency resolver uninstalling httpx; python 3.13 pre-release wheels missing for httpx deps (h11/httpcore); venv mismatch (httpx installed globally).

Related errors

• sentence-transformers is required for LocalEmbedder. Install
• openai is required for OpenAIEmbedder. Install it with: pip
• module {__name__!r} has no attribute {name!r}
• module {__name__!r} has no attribute {name!r}
• OpenAI API key required. Provide api_key parameter or set OP

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