headroomlabs-ai/headroom · error · ImportError

sentence-transformers is required for LocalEmbedder. Install

Error message

sentence-transformers is required for LocalEmbedder. Install it with: pip install sentence-transformers

What it means

LocalEmbedder (sentence-transformers based) checks for the sentence_transformers import in __init__ via _check_dependencies and raises this ImportError when the optional dependency is absent. The original ImportError is chained. Note: even with the package installed, a missing torch or a broken install can surface here first since sentence_transformers imports torch transitively.

Source

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

            ImportError: If sentence-transformers is not installed.
        """
        self._model_name = model_name or ML_MODEL_DEFAULTS.sentence_transformer
        self._requested_device = device
        self._model: SentenceTransformer | None = None
        self._device: str | None = None
        self._dimension: int | None = None
        self._lock = asyncio.Lock()
        # Dedicated single-worker executor, created only when the resolved device
        # is MPS (see _load_model). torch-MPS is not thread-safe, so every encode()
        # must run on one thread. Stays None for CPU/CUDA → default shared executor.
        self._executor: ThreadPoolExecutor | None = None

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

    def _detect_device(self) -> str:
        """Auto-detect the best available device.

        Returns:
            Device string: "cuda", "mps", or "cpu".
        """
        import torch

        if torch.cuda.is_available():
            logger.info("CUDA device detected, using GPU")
            return "cuda"
        elif torch.backends.mps.is_available():
            logger.info("MPS device detected, using Apple Silicon GPU")
            return "mps"

View on GitHub (pinned to 322425c43b)

Solutions

1. pip install sentence-transformers (as the message says) in the active environment.
2. Prefer the headroom extra if provided (e.g. pip install 'headroom[local]') so the whole set stays consistent.
3. Verify with python -c "import sentence_transformers" — if that fails with a different error (e.g. torch/MPS), fix that underlying install.
4. If you don't need local embeddings, switch to OpenAIEmbedder or OllamaEmbedder instead.

Example fix

# before
from headroom.memory.adapters.embedders import LocalEmbedder
emb = LocalEmbedder()  # ImportError: sentence-transformers is required

# after (shell)
pip install sentence-transformers
emb = LocalEmbedder()

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

if not local_embedder_available():
    raise SystemExit("pip install sentence-transformers before using LocalEmbedder")

try:
    emb = LocalEmbedder()
except ImportError as e:
    if "sentence-transformers" in str(e):
        raise SystemExit("Missing optional dep; run: pip install sentence-transformers") from e
    raise

When it happens

Trigger: Instantiating LocalEmbedder() in an environment where sentence-transformers (or its torch dependency) is not installed — e.g. base headroom install without the [local-embeddings] extra, fresh venv, or a Docker image trimmed of ML deps.

Common situations: pip install headroom without extras then using the local embedding path; CI slim images; dependency resolver dropping sentence-transformers during a conflicting upgrade; Apple Silicon wheels missing causing import failure that masquerades as absence.

Related errors

• openai is required for OpenAIEmbedder. Install it with: pip
• httpx is required for OllamaEmbedder. Install it with: pip i
• module {__name__!r} has no attribute {name!r}
• module {__name__!r} has no attribute {name!r}
• OpenAI API key required. Provide api_key parameter or set OP

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