headroomlabs-ai/headroom · error · ImportError

qdrant-client not installed. Install with: pip install qdran

Error message

qdrant-client not installed. Install with: pip install qdrant-client

What it means

Raised by DirectMem0Adapter._ensure_initialized() when 'qdrant_client' cannot be imported. The direct-mem0 backend writes vectors straight to a Qdrant instance, so qdrant-client is mandatory. It fires on the first memory operation, after the openai import succeeded but before the Neo4j/graph stage.

Source

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

                "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:
            raise ImportError(
                "qdrant-client not installed. Install with: pip install qdrant-client"
            ) from None

        # Initialize Neo4j for direct graph writes (if enabled)
        if self._config.enable_graph:
            try:
                from neo4j import GraphDatabase

                self._neo4j_driver = GraphDatabase.driver(
                    self._config.neo4j_uri,
                    auth=(self._config.neo4j_user, self._config.neo4j_password),
                )
            except ImportError:
                logger.warning("neo4j driver not installed. Graph features disabled.")
                self._neo4j_driver = None

        # Initialize Mem0 client for fallback path
        try:

View on GitHub (pinned to 322425c43b)

Solutions

pip install 'headroom-ai[memory-stack]'
Or install directly: pip install qdrant-client
Confirm the package is importable in the running interpreter: python -c 'from qdrant_client import QdrantClient'
If you do not need vector search, use the local sqlite backend instead

Example fix

# before
pip install openai  # only openai installed
await adapter.search('query')  # ImportError: qdrant-client not installed

# after
pip install 'headroom-ai[memory-stack]'
await adapter.search('query')

Defensive patterns

Strategy: validation

Validate before calling

import importlib.util

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

assert qdrant_client_available(), 'pip install "headroom-ai[memory-stack]"'

Try / catch

try:
    await backend.search('query')
except ImportError as e:
    if 'qdrant-client not installed' in str(e):
        logger.error('missing qdrant-client; install memory-stack extra')
    raise

Prevention

Use the [memory-stack] extra rather than installing pieces manually
Add a smoke test in CI that instantiates the backend and performs one write/read
Keep the app venv explicit in deployment (uv/poetry lockfiles) to avoid partial installs

When it happens

Trigger: First async call on DirectMem0Adapter (save/search/delete/etc.) with openai installed but qdrant-client missing; the try block around 'from qdrant_client import QdrantClient' plus QdrantClient(**kwargs) catches only ImportError and re-raises it with this message.

Common situations: Partial installs where openai was added manually but the memory-stack extra was skipped; slim Docker images that strip optional deps; dependency resolver conflicts downgrading/removing qdrant-client.

Related errors

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