headroomlabs-ai/headroom · critical · ImportError

sqlite-vec is required for SQLiteVectorIndex. Install with:

Error message

sqlite-vec is required for SQLiteVectorIndex. Install with: pip install sqlite-vec
Note: Requires Python built with loadable extension support. On macOS, use Homebrew Python: brew install python

What it means

ImportError raised by SQLiteVectorIndex.__init__ when the sqlite-vec extension cannot be loaded — either the package is not installed, or the Python interpreter cannot load SQLite extensions. The message includes install and platform guidance because macOS system Python is commonly built without loadable-extension support.

Source

Thrown at headroom/memory/adapters/sqlite_vector.py:222

    def __init__(
        self,
        dimension: int = 384,
        db_path: str | Path = "vectors.db",
        page_cache_size_kb: int = 8192,
    ) -> None:
        """Initialize the SQLite vector index.

        Args:
            dimension: Embedding dimension. Default 384 for MiniLM.
            db_path: Path to SQLite database file.
            page_cache_size_kb: SQLite page cache size in KB. Default 8MB.

        Raises:
            ImportError: If sqlite-vec is not available.
        """
        if not _check_sqlite_vec_available():
            raise ImportError(
                "sqlite-vec is required for SQLiteVectorIndex. "
                "Install with: pip install sqlite-vec\n"
                "Note: Requires Python built with loadable extension support. "
                "On macOS, use Homebrew Python: brew install python"
            )

        self._dimension = dimension
        self._db_path = Path(db_path)
        self._page_cache_size_kb = page_cache_size_kb
        self._lock = RLock()
        self._connections: dict[int, sqlite3.Connection] = {}

        self._init_db()

    def _create_conn(self) -> sqlite3.Connection:
        """Create a SQLite connection with sqlite-vec loaded."""
        conn = sqlite3.connect(str(self._db_path))
        conn.row_factory = sqlite3.Row

View on GitHub (pinned to 322425c43b)

Solutions

pip install sqlite-vec in the same environment/venv that runs the app.
On macOS, use Homebrew Python (brew install python) or pyenv-built Python, which enable loadable extensions.
If you cannot install extensions, switch to HNSWVectorIndex or another backend that does not need sqlite-vec.
Add sqlite-vec to your requirements/pyproject so deployments install it automatically.

Example fix

# before
index = SQLiteVectorIndex(dimension=384, db_path=p)  # ImportError

# after
# pip install sqlite-vec  (and use a Python with extension support)
index = SQLiteVectorIndex(dimension=384, db_path=p)

Defensive patterns

Strategy: try-catch

Validate before calling

try:
    import sqlite_vec  # noqa: F401
except ImportError:
    raise SystemExit("Run: pip install sqlite-vec (requires extension-capable Python)")
index = SQLiteVectorIndex(dimension=384, db_path=p)

Try / catch

try:
    index = SQLiteVectorIndex(dimension=384, db_path=p)
except ImportError:
    index = HNSWVectorIndex(dimension=384)  # fallback backend

Prevention

Add sqlite-vec to project dependencies and pin it in CI.
On macOS use Homebrew/pyenv Python; test extension loading in a smoke check at startup.
Document which environments support extension loading before users pick this backend.

When it happens

Trigger: Constructing SQLiteVectorIndex in an environment where 'pip install sqlite-vec' was never run; using macOS system Python (no extension loading); Python builds where sqlite3 was compiled without SQLITE_OMIT_LOAD_EXTENSION relief; restricted environments blocking extension loading.

Common situations: Fresh deployments missing the optional dependency; macOS default /usr/bin/python3; slim Docker images lacking build support; CI matrix differences between local and remote environments.

Related errors

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