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

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.

Source

Thrown at chromadb/utils/embedding_functions/fastembed_sparse_embedding_function.py:51

    ):
        """Initialize SparseEncoderEmbeddingFunction.

        Args:
            model_name (str, optional): Identifier of the Fastembed model
            List of commonly used models: Qdrant/bm25, prithivida/Splade_PP_en_v1, Qdrant/minicoil-v1
            task (str, optional): Task to perform, can be "document" or "query"
            cache_dir (str, optional): The path to the cache directory.
            threads (int, optional): The number of threads to use for the model.
            cuda (bool, optional): Whether to use CUDA.
            device_ids (list[int], optional): The device IDs to use for the model.
            lazy_load (bool, optional): Whether to lazy load the model.
            query_config (dict, optional): Configuration for the query, can be "task"
            **kwargs: Additional arguments to pass to the model.
        """
        try:
            from fastembed import SparseTextEmbedding
        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.model_name = model_name
        self.cache_dir = cache_dir
        self.threads = threads
        self.cuda = cuda
        self.device_ids = device_ids
        self.lazy_load = lazy_load
        validate_embedding_function_kwargs_are_safe(kwargs)
        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
        self._model = SparseTextEmbedding(
            model_name, cache_dir, threads, cuda, device_ids, lazy_load, **kwargs

View on GitHub (pinned to aecdd12c8a)

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.

Example fix

# before
from chromadb.utils.embedding_functions import FastembedSparseEmbeddingFunction
ef = FastembedSparseEmbeddingFunction(model_name='Qdrant/bm25')  # ValueError: fastembed not installed

# after
# pip install fastembed
from chromadb.utils.embedding_functions import FastembedSparseEmbeddingFunction
ef = FastembedSparseEmbeddingFunction(model_name='Qdrant/bm25', task='document')

Defensive patterns

Strategy: validation

Validate before calling

import importlib.util
if importlib.util.find_spec('fastembed') is None:
    raise SystemExit('pip install fastembed before using FastembedSparseEmbeddingFunction')

Try / catch

try:
    ef = FastembedSparseEmbeddingFunction(model_name='Qdrant/bm25')
except ValueError as e:
    if 'fastembed' in str(e):
        raise SystemExit(f'Dependency missing: {e}') from e
    raise

Prevention

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).

When it happens

Trigger: FastembedSparseEmbeddingFunction(model_name='Qdrant/bm25', ...) constructed in an environment where the fastembed distribution is not installed (the pip package name is fastembed).

Common situations: Sparse embeddings are a newer path - existing chromadb installs never pulled fastembed; minimal Docker images; adopting sparse search after the initial environment was frozen.

Related errors

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