chroma-core/chroma · error · ValueError

The snowballstemmer python package is not installed. Please

Error message

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

What it means

The BM25 tokenizer schema lazily creates a Snowball stemmer for English via get_english_stemmer() -> _SnowballStemmerAdapter, whose __init__ imports snowballstemmer and rewrites ImportError into this ValueError. It is an optional dependency used by BM25/sparse embedding functions for stemming during tokenization, so the failure occurs when the stemmer is first instantiated (e.g. building a BM25 embedding function configured with an English stemmer), not at chromadb import time.

Source

Thrown at chromadb/utils/embedding_functions/schemas/bm25_tokenizer.py:205

]


DEFAULT_CHROMA_BM25_STOPWORDS: List[str] = list(DEFAULT_ENGLISH_STOPWORDS)


class SnowballStemmer(Protocol):
    def stem(self, token: str) -> str:  # pragma: no cover - protocol definition
        ...


class _SnowballStemmerAdapter:
    """Adapter that provides the uniform `stem` API used across languages."""

    def __init__(self) -> None:
        try:
            import snowballstemmer
        except ImportError:
            raise ValueError(
                "The snowballstemmer python package is not installed. Please install it with `pip install snowballstemmer`"
            )

        self._stemmer = snowballstemmer.stemmer("english")

    def stem(self, token: str) -> str:
        return cast(str, self._stemmer.stemWord(token))


def get_english_stemmer() -> SnowballStemmer:
    """Return a Snowball stemmer for English."""
    return _SnowballStemmerAdapter()


class Bm25Tokenizer:
    """Tokenizer with stopword filtering and stemming used by BM25 embeddings."""

    def __init__(

View on GitHub (pinned to aecdd12c8a)

Solutions

pip install snowballstemmer in the target environment and pin it in requirements.txt/pyproject alongside chromadb.
If you don't need stemming, configure the BM25 tokenizer to use the no-stemmer option so the import path is never hit.
For reproducible deploys, add it to the Dockerfile: RUN pip install snowballstemmer.
Verify with python -c "import snowballstemmer" in the exact runtime (venv/container) before startup.

Example fix

// before
from chromadb.utils.embedding_functions.schemas.bm25_tokenizer import get_english_stemmer
stemmer = get_english_stemmer()  # ValueError: The snowballstemmer python package is not installed...

# after
# shell: pip install snowballstemmer
import importlib.util
if importlib.util.find_spec("snowballstemmer") is None:
    raise RuntimeError("Run: pip install snowballstemmer")
stemmer = get_english_stemmer()

Defensive patterns

Strategy: validation

Validate before calling

import importlib.util

if importlib.util.find_spec("snowballstemmer") is None:
    raise RuntimeError("snowballstemmer missing — run: pip install snowballstemmer (required for BM25 stemming)")

from chromadb.utils.embedding_functions.schemas.bm25_tokenizer import get_english_stemmer
stemmer = get_english_stemmer()

Type guard

import importlib.util

def snowball_available() -> bool:
    return importlib.util.find_spec("snowballstemmer") is not None

Try / catch

try:
    stemmer = get_english_stemmer()
except ValueError as e:
    if "snowballstemmer" in str(e):
        raise RuntimeError("Install BM25 deps: pip install snowballstemmer") from e
    raise

Prevention

When enabling BM25/sparse search, add its optional deps to the lockfile in the same commit.
Configure the no-stemmer tokenizer option in environments where stemming is not required.
Smoke-test persisted collections after dependency changes, since loading re-instantiates the tokenizer.

When it happens

Trigger: Creating a BM25-based embedding function whose tokenizer config selects the English Snowball stemmer (get_english_stemmer() path) in an environment without the package. Restoring/reloading a persisted collection whose embedding-function config includes the stemmer also re-instantiates the adapter and can trigger it on load.

Common situations: sparse/BM25 search added to an app whose dependency manifest only includes chromadb; CI or production images built before the BM25 feature was enabled, missing the new optional extra; teammates who ran pip install snowballstemmer manually and never committed it to requirements.

Related errors

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