headroomlabs-ai/headroom · error · ImportError

openai is required for OpenAIEmbedder. Install it with: pip

Error message

openai is required for OpenAIEmbedder. Install it with: pip install openai

What it means

OpenAIEmbedder._check_dependencies probes for the openai package during __init__ and raises this ImportError (chaining the original) when it is missing. The heavy client (AsyncOpenAI) is created lazily afterwards, so this check is the gate that fails before any API interaction.

Source

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

        self._check_dependencies()

        self._api_key = api_key or os.environ.get("OPENAI_API_KEY")
        if not self._api_key:
            raise ValueError(
                "OpenAI API key required. Provide api_key parameter or set "
                "OPENAI_API_KEY environment variable."
            )

        self._model_name = model_name or self.DEFAULT_MODEL
        self._max_retries = max_retries if max_retries is not None else self.MAX_RETRIES
        self._client = None

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

    @cached_property
    def _async_client(self) -> Any:
        """Lazy initialization of async OpenAI client."""
        from openai import AsyncOpenAI

        return AsyncOpenAI(api_key=self._api_key)

    async def _embed_with_retry(self, texts: list[str]) -> list[np.ndarray]:
        """Call OpenAI API with retry logic for transient failures.

        Args:
            texts: List of texts to embed.

        Returns:
            List of embedding vectors.

View on GitHub (pinned to 322425c43b)

Solutions

pip install openai in the active interpreter.
Install via headroom's extras if available so openai stays pinned with the rest.
Confirm the right interpreter: which python / pip list | grep openai — often installed in a different venv.
If offline-only, use LocalEmbedder or OllamaEmbedder instead.

Example fix

# before
emb = OpenAIEmbedder()  # ImportError: openai is required

# after (shell)
pip install openai
emb = OpenAIEmbedder()

Defensive patterns

Strategy: validation

Validate before calling

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

Try / catch

try:
    emb = OpenAIEmbedder(api_key=KEY)
except ImportError as e:
    if "openai" in str(e):
        raise SystemExit("pip install openai to use OpenAIEmbedder") from e
    raise

Prevention

Pin the embeddings extra in requirements so openai is always present in deployed envs.
Add a dependency preflight to container entrypoints.
Verify pip and python point at the same environment when installs 'disappear'.

When it happens

Trigger: Constructing OpenAIEmbedder in an environment without the openai pip package — base headroom install lacking the embeddings extra, trimmed CI images, or a venv recreated without the lockfile.

Common situations: Minimal Docker images; 'works on my machine' divergence between dev and prod envs; dependency conflicts removing openai; using Ollama-only setups that accidentally instantiate the OpenAI embedder via a shared factory default.

Related errors

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