chroma-core/chroma · error · ValueError

The fastembed python package is not installed. Please instal

Error message

The fastembed python package is not installed. Please install it with `pip install fastembed`

What it means

Bm25EmbeddingFunction (deprecated — it emits a DeprecationWarning pointing to ChromaBm25EmbeddingFunction) wraps Qdrant's fastembed Bm25 sparse model and instantiates it in __init__ via `from fastembed.sparse.bm25 import Bm25`. fastembed is an optional dependency of chromadb; when the import fails, the ImportError is re-raised as this ValueError. The model is built eagerly, so construction itself fails without the package.

Source

Thrown at chromadb/utils/embedding_functions/bm25_embedding_function.py:57

            cache_dir (str, optional): The path to the cache directory.
            k (float, optional): The k parameter in the BM25 formula. Defines the saturation of the term frequency.
            b (float, optional): The b parameter in the BM25 formula. Defines the importance of the document length.
            language (str, optional): Specifies the language for the stemmer.
            token_max_length (int, optional): The maximum length of the tokens.
            disable_stemmer (bool, optional): Disable the stemmer.
            specific_model_path (str, optional): The path to the specific model.
            query_config (dict, optional): Configuration for the query, can be "task"
            **kwargs: Additional arguments to pass to the Bm25 model.
        """
        warnings.warn(
            "Bm25EmbeddingFunction is deprecated. Please use ChromaBm25EmbeddingFunction instead.",
            DeprecationWarning,
            stacklevel=2,
        )
        try:
            from fastembed.sparse.bm25 import Bm25
        except ImportError:
            raise ValueError(
                "The fastembed python package is not installed. Please install it with `pip install fastembed`"
            )

        self.task = task
        self.query_config = query_config
        self.cache_dir = cache_dir
        self.k = k
        self.b = b
        self.avg_len = avg_len
        self.language = language
        self.token_max_length = token_max_length
        self.disable_stemmer = disable_stemmer
        self.specific_model_path = specific_model_path
        for key, value in kwargs.items():
            if not isinstance(value, (str, int, float, bool, list, dict, tuple)):
                raise ValueError(f"Keyword argument {key} is not a primitive type")
        self.kwargs = kwargs
        bm25_kwargs = {

View on GitHub (pinned to aecdd12c8a)

Solutions

1. Install the dependency: pip install fastembed.
2. Prefer the non-deprecated ChromaBm25EmbeddingFunction from chromadb.utils.embedding_functions.chroma_bm25_embedding_function (still needs fastembed, but is the supported path).
3. Pin fastembed alongside chromadb in requirements so sparse features never regress on rebuild.

Example fix

# before: ValueError "The fastembed python package is not installed..."
ef = Bm25EmbeddingFunction(task="document")

# after: pip install fastembed
from chromadb.utils.embedding_functions import ChromaBm25EmbeddingFunction  # supported path
ef = ChromaBm25EmbeddingFunction()

import importlib.util

if importlib.util.find_spec("fastembed") is None:
    raise RuntimeError("fastembed is required for BM25 sparse embeddings; run: pip install fastembed")

from chromadb.utils.embedding_functions import ChromaBm25EmbeddingFunction  # preferred, non-deprecated
ef = ChromaBm25EmbeddingFunction()

try:
    ef = ChromaBm25EmbeddingFunction()
except ValueError as e:
    if "fastembed" in str(e):
        raise RuntimeError("Install fastembed to use BM25: pip install fastembed") from e
    raise

When it happens

Trigger: Constructing Bm25EmbeddingFunction(task="document", ...) in an environment without fastembed; also deserializing a "bm25" config via config_to_embedding_function, since build_from_config calls the same constructor.

Common situations: Sparse-retrieval prototypes on minimal installs; CI without the fastembed extra; Docker images built from a bare `pip install chromadb`.

Related errors

• Keyword argument {key} is not a primitive type
• Invalid task: {self.task}
• Invalid task: {task}
• The PIL python package is not installed. Please install it w
• Failed to register sparse embedding function: {e}

AI-assisted analysis of chroma-core/chroma@aecdd12c8a (2026-08-16). Data as JSON: /api/errors/6acfe0db266cfb62. Report an issue: GitHub.