chroma-core/chroma · error · ValueError

The InstructorEmbedding python package is not installed. Ple

Error message

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

What it means

InstructorEmbeddingFunction lazily imports InstructorEmbedding.INSTRUCTOR in __init__ and converts an ImportError into this ValueError. InstructorEmbedding is an optional dependency of chromadb, so it must be installed separately. The error fires at construction time, i.e. as soon as you instantiate the EF, before any embedding happens.

Source

Thrown at chromadb/utils/embedding_functions/instructor_embedding_function.py:34

        model_name: str = "hkunlp/instructor-base",
        device: str = "cpu",
        instruction: Optional[str] = None,
    ):
        """
        Initialize the InstructorEmbeddingFunction.

        Args:
            model_name (str, optional): The name of the model to use for text embeddings.
                Defaults to "hkunlp/instructor-base".
            device (str, optional): The device to use for computation.
                Defaults to "cpu".
            instruction (str, optional): The instruction to use for the embeddings.
                Defaults to None.
        """
        try:
            from InstructorEmbedding import INSTRUCTOR
        except ImportError:
            raise ValueError(
                "The InstructorEmbedding python package is not installed. Please install it with `pip install InstructorEmbedding`"
            )

        self.model_name = model_name
        self.device = device
        self.instruction = instruction

        self._model = INSTRUCTOR(model_name_or_path=model_name, device=device)

    def __call__(self, input: Documents) -> Embeddings:
        """
        Generate embeddings for the given documents.

        Args:
            input: Documents or images to generate embeddings for.

        Returns:
            Embeddings for the documents.

View on GitHub (pinned to aecdd12c8a)

Solutions

pip install InstructorEmbedding in the active interpreter
Confirm with python -c "from InstructorEmbedding import INSTRUCTOR; print('ok')" to catch broken installs (torch/transformers conflicts)
If the install conflicts, consider ONNXMiniLM_L6_V2 (chromadb default) or another text EF with lighter deps

Example fix

# before
from chromadb.utils import embedding_functions
ef = embedding_functions.InstructorEmbeddingFunction(model_name="hkunlp/instructor-base")  # ValueError

# after
# pip install InstructorEmbedding
import importlib.util
if importlib.util.find_spec("InstructorEmbedding") is None:
    raise SystemExit("pip install InstructorEmbedding")
ef = embedding_functions.InstructorEmbeddingFunction(model_name="hkunlp/instructor-base")

Defensive patterns

Strategy: validation

Validate before calling

import importlib.util

if importlib.util.find_spec("InstructorEmbedding") is None:
    raise SystemExit("Install optional dep: pip install InstructorEmbedding")

from chromadb.utils import embedding_functions
ef = embedding_functions.InstructorEmbeddingFunction(
    model_name="hkunlp/instructor-base", device="cpu"
)

Try / catch

try:
    ef = InstructorEmbeddingFunction(model_name="hkunlp/instructor-base")
except ValueError as e:
    if "InstructorEmbedding" in str(e):
        raise RuntimeError("pip install InstructorEmbedding") from e
    raise

Prevention

List InstructorEmbedding (plus torch/transformers pins) in the same requirements file as chromadb
Smoke-test `from InstructorEmbedding import INSTRUCTOR` in CI for the exact interpreter used at runtime
Prefer lighter EFs in environments where torch-based packages are unwelcome

When it happens

Trigger: InstructorEmbeddingFunction(model_name='hkunlp/instructor-base', device='cpu') in an environment where `pip install InstructorEmbedding` was never run; a fresh clone + chromadb install followed by selecting the Instructor EF; an env where the package's heavy deps (torch, transformers) failed to install.

Common situations: New project setup copying tutorial code that uses Instructor embeddings; requirements files listing chromadb but not InstructorEmbedding; installing on platforms where InstructorEmbedding's pinned transformers version conflicts and the install silently partially failed.

Related errors

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