chroma-core/chroma · error · ValueError

The onnxruntime python package is not installed. Please inst

Error message

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

What it means

ONNXMiniLM_L6_V2 imports onnxruntime lazily via importlib.import_module("onnxruntime") in __init__ and wraps ImportError in a ValueError with install instructions. This class is Chroma's default local embedding function, so hitting this means the chromadb default-extra dependency chain (onnxruntime, tokenizers, tqdm) is not installed in the current environment. Everything else in the constructor (model download, tokenizer setup) depends on this module.

Source

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

        """
        # convert the list to set for unique values
        if preferred_providers and not all(
            [isinstance(i, str) for i in preferred_providers]
        ):
            raise ValueError("Preferred providers must be a list of strings")
        # check for duplicate providers
        if preferred_providers and len(preferred_providers) != len(
            set(preferred_providers)
        ):
            raise ValueError("Preferred providers must be unique")

        self._preferred_providers = preferred_providers

        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

View on GitHub (pinned to aecdd12c8a)

Solutions

pip install onnxruntime (or reinstall chromadb with its default extras: pip install 'chromadb' which pulls onnxruntime>=1.14.1)
If you need GPU, install onnxruntime-gpu INSTEAD of onnxruntime — both register the same import name and cannot coexist
Verify the install is in the right interpreter: python -c "import onnxruntime; print(onnxruntime.__version__)"

Example fix

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

// after (shell)
pip install onnxruntime
# or for GPU: pip uninstall onnxruntime && pip install onnxruntime-gpu
// then
fn = ONNXMiniLM_L6_V2()

Defensive patterns

Strategy: validation

Validate before calling

import importlib.util
if importlib.util.find_spec("onnxruntime") is None:
    raise SystemExit("onnxruntime missing: pip install onnxruntime (or onnxruntime-gpu)")
fn = ONNXMiniLM_L6_V2()

Try / catch

try:
    ef = ONNXMiniLM_L6_V2()
except ValueError as e:
    if "onnxruntime" in str(e) and "not installed" in str(e):
        raise SystemExit("Install onnxruntime (CPU) or onnxruntime-gpu (NVIDIA) and retry") from e
    raise

Prevention

Never install onnxruntime and onnxruntime-gpu together — they collide on the same import name
Include chromadb's default extras in Docker images if you rely on the default EF
Add a startup import check for onnxruntime/tokenizers/tqdm in slim deployments

When it happens

Trigger: Instantiating ONNXMiniLM_L6_V2() or letting Chroma use its default EF after a bare `pip install chromadb` without extras in an env that also lacks onnxruntime; a fresh CI image; installing chromadb with `--no-deps`; a venv where onnxruntime was uninstalled during a dependency-resolver conflict (it conflicts with onnxruntime-gpu since both provide the same package name).

Common situations: Docker slim images that trimmed "heavy" dependencies; installing onnxruntime-gpu alongside onnxruntime and pip removing one; version pinning tools (pip-tools/poetry) resolving onnxruntime out; upgrading Python versions and reinstalling only chromadb.

Related errors

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