headroomlabs-ai/headroom · error · ImportError

hnswlib is required for HNSWVectorIndex. Install with: pip i

Error message

hnswlib is required for HNSWVectorIndex. Install with: pip install hnswlib
Note: hnswlib requires C++ compilation and may not be available on all platforms (crashes with SIGILL on CPUs without AVX support).

What it means

HNSWVectorIndex.__init__ checks hnswlib availability via _check_hnswlib_available() and raises this ImportError when the native package is absent or unloadable. The message warns that hnswlib needs C++ compilation and is platform-fragile — notably crashing with SIGILL on CPUs lacking AVX — because the wheel either can't be built or the binary faults at runtime on old hardware.

Source

Thrown at headroom/memory/adapters/hnsw.py:261

            ef_construction: HNSW construction parameter. Higher = better quality,
                           slower construction. Default: 200
            m: HNSW links per element. Higher = better recall, more memory.
               Default: 16
            ef_search: HNSW search parameter. Higher = better recall, slower
                      search. Default: 50
            auto_save: If True and save_path is set, automatically save
                      index after modifications.
            save_path: Path for auto-save operations. Required if auto_save=True.
            max_entries: Soft limit on number of entries. When reached,
                        lowest importance entries are evicted. None = unbounded.
            eviction_batch_size: Number of entries to evict when limit is reached.

        Raises:
            ValueError: If auto_save is True but save_path is not provided.
            ImportError: If hnswlib is not installed.
        """
        if not _check_hnswlib_available():
            raise ImportError(
                "hnswlib is required for HNSWVectorIndex. "
                "Install with: pip install hnswlib\n"
                "Note: hnswlib requires C++ compilation and may not be "
                "available on all platforms (crashes with SIGILL on CPUs "
                "without AVX support)."
            )

        if auto_save and save_path is None:
            raise ValueError("save_path must be provided when auto_save is True")

        self._dimension = dimension
        self._max_elements = max_elements
        self._ef_construction = ef_construction
        self._m = m
        self._ef_search = ef_search
        self._auto_save = auto_save
        self._save_path = Path(save_path) if save_path else None

View on GitHub (pinned to 322425c43b)

Solutions

1. pip install hnswlib (with build-essential / a C++ compiler available if no wheel exists for your platform).
2. On pre-AVX hardware, do NOT install it — use SQLiteVectorIndex instead, which is pure-SQL and safe everywhere.
3. In Dockerfiles, install gcc/g++ before pip install if you must build from source.
4. Confirm importability first: python -c "import hnswlib" to separate install failure from constructor failure.

Example fix

# before
from headroom.memory.adapters import HNSWVectorIndex
idx = HNSWVectorIndex(dimension=384)  # ImportError: hnswlib required

# after
from headroom.memory.adapters import SQLiteVectorIndex
idx = SQLiteVectorIndex(dimension=384)  # portable fallback, no native deps

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

VectorIndex = HNSWVectorIndex if hnsw_safe() else SQLiteVectorIndex

try:
    idx = HNSWVectorIndex(dimension=dim)
except ImportError as e:
    if "hnswlib" in str(e):
        idx = SQLiteVectorIndex(dimension=dim)  # documented portable fallback
    else:
        raise

When it happens

Trigger: Constructing HNSWVectorIndex() where hnswlib is not installed, failed to compile during install (no C++ toolchain), or was avoided deliberately on pre-AVX CPUs. Headroom treats it as an optional vector-index adapter for exactly this reason.

Common situations: Alpine/slim Docker images without gcc; older Xeon/desktop CPUs without AVX where the shipped wheel raises SIGILL; python versions with no prebuilt hnswlib wheel; CI environments intentionally excluding native deps.

Related errors

• sentence-transformers is required for LocalEmbedder. Install
• openai is required for OpenAIEmbedder. Install it with: pip
• httpx is required for OllamaEmbedder. Install it with: pip i
• save_path must be provided when auto_save is True
• Memory {memory.id} has no embedding

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