langchain-ai/langchain · error · ImportError

numpy must be installed to use max_marginal_relevance_search

Error message

numpy must be installed to use max_marginal_relevance_search pip install numpy

What it means

InMemoryVectorStore.max_marginal_relevance_search (via its internal MMR helper) raises this ImportError when numpy is not installed in the environment. numpy is an optional dependency for langchain-core vectorstores: plain similarity_search works without it, but maximal-marginal-relevance reranking needs numpy math (via maximal_marginal_relevance), so the import flag _HAS_NUMPY gates it. The check occurs after the prefetch similarity search has already run, so k candidate hits are fetched before the error surfaces.

Source

Thrown at libs/core/langchain_core/vectorstores/in_memory.py:440

        k: int = 4,
        fetch_k: int = 20,
        lambda_mult: float = 0.5,
        *,
        filter: Callable[[Document], bool] | None = None,
        **kwargs: Any,
    ) -> list[Document]:
        prefetch_hits = self._similarity_search_with_score_by_vector(
            embedding=embedding,
            k=fetch_k,
            filter=filter,
        )

        if not _HAS_NUMPY:
            msg = (
                "numpy must be installed to use max_marginal_relevance_search "
                "pip install numpy"
            )
            raise ImportError(msg)

        mmr_chosen_indices = maximal_marginal_relevance(
            np.array(embedding, dtype=np.float32),
            [vector for _, _, vector in prefetch_hits],
            k=k,
            lambda_mult=lambda_mult,
        )
        return [prefetch_hits[idx][0] for idx in mmr_chosen_indices]

    @override
    def max_marginal_relevance_search(
        self,
        query: str,
        k: int = 4,
        fetch_k: int = 20,
        lambda_mult: float = 0.5,
        **kwargs: Any,
    ) -> list[Document]:

View on GitHub (pinned to e32fa9a52e)

Solutions

Install numpy in the environment: pip install numpy (or add numpy to the deployment's requirements).
If image size allowed the omission, install a prebuilt numpy wheel rather than excluding it; MMR reranking has no numpy-free fallback in this code path.
If numpy cannot be added, switch the call to store.similarity_search(query, k=k) which needs no numpy, accepting no diversity reranking.
Feature-detect up front (import numpy in a try/except at startup) and disable/configure MMR search off when unavailable, so the failure is explicit rather than mid-request.

Example fix

// before
results = store.max_marginal_relevance_search(query, k=4, fetch_k=20)  # ImportError without numpy

// after (option 1: install dependency)
// pip install numpy
results = store.max_marginal_relevance_search(query, k=4, fetch_k=20)

// after (option 2: degrade gracefully)
from langchain_core.vectorstores import InMemoryVectorStore
try:
    import numpy  # noqa: F401
    results = store.max_marginal_relevance_search(query, k=4, fetch_k=20)
except ImportError:
    results = store.similarity_search(query, k=4)

Defensive patterns

Strategy: fallback

Validate before calling

try:
    import numpy  # noqa: F401
    HAS_NUMPY = True
except ImportError:
    HAS_NUMPY = False

if not HAS_NUMPY:
    raise RuntimeError("max_marginal_relevance_search requires numpy; pip install numpy")

Type guard

def supports_mmr() -> bool:
    """True when numpy is importable, i.e. MMR search is usable."""
    try:
        import numpy  # noqa: F401
    except ImportError:
        return False
    return True

Try / catch

try:
    results = store.max_marginal_relevance_search(query, k=4, fetch_k=20)
except ImportError as e:
    if "numpy" in str(e):
        logger.warning("numpy missing; falling back to similarity_search")
        results = store.similarity_search(query, k=4)
    else:
        raise

Prevention

Pin numpy in the deployment's dependency file whenever you use MMR search — it is not optional there.
Probe numpy availability at startup and configure search_type ('mmr' vs 'similarity') accordingly.
Include an MMR call in CI smoke tests so a trimmed environment fails at build time, not in production.
Document in the service's README/Dockerfile that MMR requires numpy.

When it happens

Trigger: Calling store.max_marginal_relevance_search(query, k=..., fetch_k=...) (or max_marginal_relevance_search_with_score) in an environment where `import numpy` failed — e.g. a minimal container or lambda image that installed langchain-core without the numpy extra. The prefetch _similarity_search_with_score_by_vector succeeds (pure Python), then _HAS_NUMPY is False and the ImportError fires.

Common situations: Slim Docker/lambda deployments that pip-install langchain without numpy to reduce image size; adding MMR search to code that originally only used similarity_search (which worked fine without numpy); CI environments with a trimmed dependency set where tests for MMR suddenly fail after a refactor.

Related errors

AI-assisted analysis of langchain-ai/langchain@e32fa9a52e (2026-08-14). Data as JSON: /api/errors/e7026d383ba4d9c6. Report an issue: GitHub.