headroomlabs-ai/headroom · error · ImportError

openai package not installed. Install with: pip install open

Error message

openai package not installed. Install with: pip install openai

What it means

Raised by DirectMem0Adapter._ensure_initialized() when the 'openai' Python package cannot be imported. The direct-mem0 backend embeds memories with OpenAI embeddings, so the openai SDK is a hard runtime dependency for this backend. Initialization is lazy: the ImportError surfaces on the first memory operation (save/search/update), not at construction time.

Source

Thrown at headroom/memory/backends/direct_mem0.py:177

        self._initialized = False

        # Background task tracking
        self._background_tasks: dict[str, asyncio.Task] = {}
        self._task_results: dict[str, dict[str, Any]] = {}
        self._close_lock = asyncio.Lock()

    async def _ensure_initialized(self) -> None:
        """Ensure all clients are initialized."""
        if self._initialized:
            return

        # Initialize embedder (OpenAI)
        try:
            from openai import OpenAI

            self._openai_client = OpenAI()
        except ImportError:
            raise ImportError(
                "openai package not installed. Install with: pip install openai"
            ) from None

        # Initialize Qdrant client for direct writes
        try:
            from qdrant_client import QdrantClient

            client_kwargs = qdrant_env.build_qdrant_client_kwargs(
                url=self._config.qdrant_url,
                host=self._config.qdrant_host,
                port=self._config.qdrant_port,
                api_key=self._config.qdrant_api_key,
                https=self._config.qdrant_https,
                prefer_grpc=self._config.qdrant_prefer_grpc,
                grpc_port=self._config.qdrant_grpc_port,
            )
            self._qdrant_client = QdrantClient(**client_kwargs)
        except ImportError:

View on GitHub (pinned to 322425c43b)

Solutions

1. pip install 'headroom-ai[memory-stack]' (installs openai, qdrant-client, and mem0 together)
2. Or install the single missing package: pip install openai
3. Or switch to a backend with no extra deps (e.g. the sqlite/local backend)
4. Verify the right interpreter: python -c 'import openai' in the same venv the app runs in

Example fix

# before
pip install headroom-ai
adapter = DirectMem0Adapter(cfg)
await adapter.save('note', user_id='u1')  # ImportError: openai package not installed

# after
pip install 'headroom-ai[memory-stack]'
adapter = DirectMem0Adapter(cfg)
await adapter.save('note', user_id='u1')

import importlib.util

def openai_available() -> bool:
    return importlib.util.find_spec('openai') is not None

# before constructing the backend
if not openai_available():
    raise SystemExit('Install extras first: pip install "headroom-ai[memory-stack]"')

try:
    await adapter.save(content, user_id='u1')
except ImportError as e:
    if 'openai package not installed' in str(e):
        logger.error('memory backend missing deps; run: pip install "headroom-ai[memory-stack]"')
    raise

When it happens

Trigger: Creating DirectMem0Adapter (or MemoryEasy with backend 'qdrant-neo4j') and calling any async memory operation such as save(), search(), or update_memory(); the first call runs _ensure_initialized(), which does 'from openai import OpenAI' and raises ImportError on failure.

Common situations: Installing headroom-ai without the [memory-stack] extra; running in a venv/CI image that only pinned core dependencies; openai installed in a different interpreter than the one running the app.

Related errors

• qdrant-client not installed. Install with: pip install qdran
• mem0 package not installed. Install with: pip install 'headr
• mem0 package not installed. Install with: pip install 'headr
• qdrant-neo4j backend requires additional packages. Install w
• Magika is required for ML-based content detection. Install w

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