{"record":{"id":"6acfe0db266cfb62","repo":"chroma-core/chroma","slug":"the-fastembed-python-package-is-not-installed-ple","errorCode":null,"errorMessage":"The fastembed python package is not installed. Please install it with `pip install fastembed`","messagePattern":"The fastembed python package is not installed\\. Please install it with `pip install fastembed`","errorType":"exception","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"chromadb/utils/embedding_functions/bm25_embedding_function.py","lineNumber":57,"sourceCode":"            cache_dir (str, optional): The path to the cache directory.\n            k (float, optional): The k parameter in the BM25 formula. Defines the saturation of the term frequency.\n            b (float, optional): The b parameter in the BM25 formula. Defines the importance of the document length.\n            language (str, optional): Specifies the language for the stemmer.\n            token_max_length (int, optional): The maximum length of the tokens.\n            disable_stemmer (bool, optional): Disable the stemmer.\n            specific_model_path (str, optional): The path to the specific model.\n            query_config (dict, optional): Configuration for the query, can be \"task\"\n            **kwargs: Additional arguments to pass to the Bm25 model.\n        \"\"\"\n        warnings.warn(\n            \"Bm25EmbeddingFunction is deprecated. Please use ChromaBm25EmbeddingFunction instead.\",\n            DeprecationWarning,\n            stacklevel=2,\n        )\n        try:\n            from fastembed.sparse.bm25 import Bm25\n        except ImportError:\n            raise ValueError(\n                \"The fastembed python package is not installed. Please install it with `pip install fastembed`\"\n            )\n\n        self.task = task\n        self.query_config = query_config\n        self.cache_dir = cache_dir\n        self.k = k\n        self.b = b\n        self.avg_len = avg_len\n        self.language = language\n        self.token_max_length = token_max_length\n        self.disable_stemmer = disable_stemmer\n        self.specific_model_path = specific_model_path\n        for key, value in kwargs.items():\n            if not isinstance(value, (str, int, float, bool, list, dict, tuple)):\n                raise ValueError(f\"Keyword argument {key} is not a primitive type\")\n        self.kwargs = kwargs\n        bm25_kwargs = {","sourceCodeStart":39,"sourceCodeEnd":75,"githubUrl":"https://github.com/chroma-core/chroma/blob/aecdd12c8a891610db8653630b066b32ceb678b5/chromadb/utils/embedding_functions/bm25_embedding_function.py#L39-L75","documentation":"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.","triggerScenarios":"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.","commonSituations":"Sparse-retrieval prototypes on minimal installs; CI without the fastembed extra; Docker images built from a bare `pip install chromadb`.","solutions":["Install the dependency: pip install fastembed.","Prefer the non-deprecated ChromaBm25EmbeddingFunction from chromadb.utils.embedding_functions.chroma_bm25_embedding_function (still needs fastembed, but is the supported path).","Pin fastembed alongside chromadb in requirements so sparse features never regress on rebuild."],"exampleFix":"# before: ValueError \"The fastembed python package is not installed...\"\nef = Bm25EmbeddingFunction(task=\"document\")\n\n# after: pip install fastembed\nfrom chromadb.utils.embedding_functions import ChromaBm25EmbeddingFunction  # supported path\nef = ChromaBm25EmbeddingFunction()","handlingStrategy":"validation","validationCode":"import importlib.util\n\nif importlib.util.find_spec(\"fastembed\") is None:\n    raise RuntimeError(\"fastembed is required for BM25 sparse embeddings; run: pip install fastembed\")\n\nfrom chromadb.utils.embedding_functions import ChromaBm25EmbeddingFunction  # preferred, non-deprecated\nef = ChromaBm25EmbeddingFunction()","typeGuard":null,"tryCatchPattern":"try:\n    ef = ChromaBm25EmbeddingFunction()\nexcept ValueError as e:\n    if \"fastembed\" in str(e):\n        raise RuntimeError(\"Install fastembed to use BM25: pip install fastembed\") from e\n    raise","preventionTips":["Migrate off the deprecated Bm25EmbeddingFunction to ChromaBm25EmbeddingFunction.","Add fastembed to the lockfile wherever sparse retrieval features are enabled.","Probe find_spec('fastembed') at startup in services that own sparse collections."],"tags":["python","fastembed","bm25","sparse-embedding","optional-dependency","deprecated","chromadb"],"backgroundTag":"missing-optional-dependency","analyzedSha":"aecdd12c8a891610db8653630b066b32ceb678b5","analyzedAt":"2026-08-16T21:53:27.228Z","schemaVersion":2},"datasetVersion":"2026-08-16T23:17:17.608Z"}