chroma-core/chroma · error · ValueError

The onnxruntime python package is not installed. Please…

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.

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.

Understand the failure class

Background: "not installed", "pip install", "required for": how missing-dependency errors surface across open-source libraries — this error's family across 34 libraries.

Related errors

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

Appendix: 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)