headroomlabs-ai/headroom · error · ImportError

numpy is required for EmbeddingScorer. Install with: pip ins

Error message

numpy is required for EmbeddingScorer. Install with: pip install headroom[relevance]

What it means

Raised lazily by _get_numpy() in the embedding module the first time numpy is needed and the import fails. numpy is part of the optional [relevance] extra; the error surfaces only at use time because the import is deferred to keep base installs light.

Source

Thrown at headroom/relevance/embedding.py:48

import os
from typing import TYPE_CHECKING

from .base import RelevanceScore, RelevanceScorer

# numpy is an optional dependency - import lazily
_numpy = None


def _get_numpy():
    """Lazily import numpy."""
    global _numpy
    if _numpy is None:
        try:
            import numpy as np

            _numpy = np
        except ImportError as e:
            raise ImportError(
                "numpy is required for EmbeddingScorer. "
                "Install with: pip install headroom[relevance]"
            ) from e
    return _numpy


if TYPE_CHECKING:
    from fastembed import TextEmbedding

logger = logging.getLogger(__name__)

# Default model name. Same string used by the Rust embedding scorer.
DEFAULT_MODEL_NAME = "BAAI/bge-small-en-v1.5"

# Pinned revision of fastembed's underlying HF repo for the default model
# (fastembed resolves "BAAI/bge-small-en-v1.5" -> "qdrant/bge-small-en-v1.5-onnx-q").
# fastembed's TextEmbedding signature omits ``revision`` but forwards **kwargs to
# huggingface_hub.snapshot_download, so passing it pins the download for

View on GitHub (pinned to 322425c43b)

Solutions

1. Install the extra: pip install 'headroom[relevance]' (pulls a compatible numpy).
2. Verify with 'python -c "import numpy"' in the same interpreter/venv your app runs in.
3. If numpy conflicts with another package, pin a version compatible with both or isolate headroom in its own venv.

Example fix

# before
scorer.score(query, docs)  # ImportError: numpy required

# after
# pip install 'headroom[relevance]'
scorer.score(query, docs)

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

if not numpy_available():
    scorer = create_scorer('bm25')  # avoid failing mid-request

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

try:
    score = scorer.score(query, docs)
except ImportError as e:
    if 'numpy' in str(e):
        scorer = create_scorer('bm25')
        score = scorer.score(query, docs)
    else:
        raise

When it happens

Trigger: Calling any EmbeddingScorer scoring/embedding method in an environment where numpy is not installed, after having satisfied the fastembed availability probe.

Common situations: Partial installs where fastembed is present but numpy is missing or broken (wrong ABI for another package); slim containers; downgrading numpy-breaking environments.

Related errors

• EmbeddingScorer requires fastembed. Install with: pip instal
• jinja2 is required for report generation. Install with: pip
• EmbeddingScorer requires sentence-transformers. Install with
• No optimizer registered for '{key}'. Available: {available}
• httpx is required for Headroom Cloud mode: pip install httpx

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