chroma-core/chroma · error · ValueError

The tqdm python package is not installed. Please install it

Error message

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

What it means

The third lazy import in ONNXMiniLM_L6_V2.__init__ is tqdm (importlib.import_module("tqdm").tqdm); ImportError becomes ValueError with the pip hint. tqdm is only used to render a progress bar while downloading the ONNX model file into ~/.cache/chroma/onnx_models/, but it is unconditionally required at construction, so a missing tqdm fails even before any download starts.

Source

Thrown at chromadb/utils/embedding_functions/onnx_mini_lm_l6_v2.py:86

        try:
            # Equivalent to import onnxruntime
            self.ort = importlib.import_module("onnxruntime")
        except ImportError:
            raise ValueError(
                "The onnxruntime python package is not installed. Please install it with `pip install onnxruntime`"
            )
        try:
            # Equivalent to from tokenizers import Tokenizer
            self.Tokenizer = importlib.import_module("tokenizers").Tokenizer
        except ImportError:
            raise ValueError(
                "The tokenizers python package is not installed. Please install it with `pip install tokenizers`"
            )
        try:
            # Equivalent to from tqdm import tqdm
            self.tqdm = importlib.import_module("tqdm").tqdm
        except ImportError:
            raise ValueError(
                "The tqdm python package is not installed. Please install it with `pip install tqdm`"
            )

    # Borrowed from https://gist.github.com/yanqd0/c13ed29e29432e3cf3e7c38467f42f51
    # Download with tqdm to preserve the sentence-transformers experience
    @retry(  # type: ignore
        reraise=True,
        stop=stop_after_attempt(3),
        wait=wait_random(min=1, max=3),
        retry=retry_if_exception(lambda e: "does not match expected SHA256" in str(e)),
    )
    def _download(self, url: str, fname: str, chunk_size: int = 1024) -> None:
        """
        Download the onnx model from the URL and save it to the file path.

        Args:
            url: The URL to download the model from.
            fname: The path to save the model to.

View on GitHub (pinned to aecdd12c8a)

Solutions

pip install tqdm
Or restore the full default dependency set: pip install --force-reinstall chromadb
Add tqdm to your lockfile so it is present in every environment that instantiates this EF

Example fix

// before
fn = ONNXMiniLM_L6_V2()  # ValueError: tqdm not installed

// after (shell)
pip install tqdm
// then
fn = ONNXMiniLM_L6_V2()

Defensive patterns

Strategy: validation

Validate before calling

import importlib.util
if importlib.util.find_spec("tqdm") is None:
    raise SystemExit("tqdm missing (used for model download progress): pip install tqdm")
ef = ONNXMiniLM_L6_V2()

Try / catch

try:
    ef = ONNXMiniLM_L6_V2()
except ValueError as e:
    if "tqdm" in str(e):
        raise SystemExit("Run: pip install tqdm") from e
    raise

Prevention

Don't strip tqdm from slim images if the default EF will download its model there
Pre-download the model on a build stage that has tqdm, then ship the ~/.cache/chroma/onnx_models directory

When it happens

Trigger: Constructing ONNXMiniLM_L6_V2() where chromadb's default extras were not installed and tqdm is absent; environments that deliberately exclude tqdm (some minimal runners consider it bloat); dependency resolvers dropping tqdm after a conflict.

Common situations: Minimal production/CI images that strip dev-niceties like tqdm; Lambdas/serverless builds minimizing package size; fresh venvs created from a hand-maintained requirements list that omits tqdm.

Related errors

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