{"record":{"id":"1374c19f7eb2c87f","repo":"chroma-core/chroma","slug":"the-fastembed-python-package-is-not-installed-ple-1374c1","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/fastembed_sparse_embedding_function.py","lineNumber":51,"sourceCode":"    ):\n        \"\"\"Initialize SparseEncoderEmbeddingFunction.\n\n        Args:\n            model_name (str, optional): Identifier of the Fastembed model\n            List of commonly used models: Qdrant/bm25, prithivida/Splade_PP_en_v1, Qdrant/minicoil-v1\n            task (str, optional): Task to perform, can be \"document\" or \"query\"\n            cache_dir (str, optional): The path to the cache directory.\n            threads (int, optional): The number of threads to use for the model.\n            cuda (bool, optional): Whether to use CUDA.\n            device_ids (list[int], optional): The device IDs to use for the model.\n            lazy_load (bool, optional): Whether to lazy load the model.\n            query_config (dict, optional): Configuration for the query, can be \"task\"\n            **kwargs: Additional arguments to pass to the model.\n        \"\"\"\n        try:\n            from fastembed import SparseTextEmbedding\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.model_name = model_name\n        self.cache_dir = cache_dir\n        self.threads = threads\n        self.cuda = cuda\n        self.device_ids = device_ids\n        self.lazy_load = lazy_load\n        validate_embedding_function_kwargs_are_safe(kwargs)\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        self._model = SparseTextEmbedding(\n            model_name, cache_dir, threads, cuda, device_ids, lazy_load, **kwargs","sourceCodeStart":33,"sourceCodeEnd":69,"githubUrl":"https://github.com/chroma-core/chroma/blob/aecdd12c8a891610db8653630b066b32ceb678b5/chromadb/utils/embedding_functions/fastembed_sparse_embedding_function.py#L33-L69","documentation":"FastembedSparseEmbeddingFunction imports fastembed's SparseTextEmbedding lazily inside __init__; without the package, construction fails immediately with this ValueError. The same import is re-checked at __call__ and embed_query time (errors 777/779), so the dependency must be present for the whole process lifetime, not just at construction.","triggerScenarios":"FastembedSparseEmbeddingFunction(model_name='Qdrant/bm25', ...) constructed in an environment where the fastembed distribution is not installed (the pip package name is fastembed).","commonSituations":"Sparse embeddings are a newer path - existing chromadb installs never pulled fastembed; minimal Docker images; adopting sparse search after the initial environment was frozen.","solutions":["pip install fastembed, then re-instantiate the function.","Add fastembed to your dependency manifest next to chromadb.","Verify with python -c 'from fastembed import SparseTextEmbedding' in the runtime interpreter."],"exampleFix":"# before\nfrom chromadb.utils.embedding_functions import FastembedSparseEmbeddingFunction\nef = FastembedSparseEmbeddingFunction(model_name='Qdrant/bm25')  # ValueError: fastembed not installed\n\n# after\n# pip install fastembed\nfrom chromadb.utils.embedding_functions import FastembedSparseEmbeddingFunction\nef = FastembedSparseEmbeddingFunction(model_name='Qdrant/bm25', task='document')","handlingStrategy":"validation","validationCode":"import importlib.util\nif importlib.util.find_spec('fastembed') is None:\n    raise SystemExit('pip install fastembed before using FastembedSparseEmbeddingFunction')","typeGuard":null,"tryCatchPattern":"try:\n    ef = FastembedSparseEmbeddingFunction(model_name='Qdrant/bm25')\nexcept ValueError as e:\n    if 'fastembed' in str(e):\n        raise SystemExit(f'Dependency missing: {e}') from e\n    raise","preventionTips":["Add fastembed to the manifest when adopting sparse embeddings.","Remember fastembed is re-imported at __call__/embed_query time - install it on servers too.","Boot-check optional provider imports in every environment (client, server, CI)."],"tags":["chroma","fastembed","missing-dependency","sparse-embeddings","embedding-function"],"backgroundTag":"missing-python-package","analyzedSha":"aecdd12c8a891610db8653630b066b32ceb678b5","analyzedAt":"2026-08-16T21:53:27.228Z","schemaVersion":2},"datasetVersion":"2026-08-16T23:17:17.608Z"}