{"record":{"id":"75217d11fccc1d8d","repo":"chroma-core/chroma","slug":"the-instructorembedding-python-package-is-not-inst","errorCode":null,"errorMessage":"The InstructorEmbedding python package is not installed. Please install it with `pip install InstructorEmbedding`","messagePattern":"The InstructorEmbedding python package is not installed\\. Please install it with `pip install InstructorEmbedding`","errorType":"exception","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"chromadb/utils/embedding_functions/instructor_embedding_function.py","lineNumber":34,"sourceCode":"        model_name: str = \"hkunlp/instructor-base\",\n        device: str = \"cpu\",\n        instruction: Optional[str] = None,\n    ):\n        \"\"\"\n        Initialize the InstructorEmbeddingFunction.\n\n        Args:\n            model_name (str, optional): The name of the model to use for text embeddings.\n                Defaults to \"hkunlp/instructor-base\".\n            device (str, optional): The device to use for computation.\n                Defaults to \"cpu\".\n            instruction (str, optional): The instruction to use for the embeddings.\n                Defaults to None.\n        \"\"\"\n        try:\n            from InstructorEmbedding import INSTRUCTOR\n        except ImportError:\n            raise ValueError(\n                \"The InstructorEmbedding python package is not installed. Please install it with `pip install InstructorEmbedding`\"\n            )\n\n        self.model_name = model_name\n        self.device = device\n        self.instruction = instruction\n\n        self._model = INSTRUCTOR(model_name_or_path=model_name, device=device)\n\n    def __call__(self, input: Documents) -> Embeddings:\n        \"\"\"\n        Generate embeddings for the given documents.\n\n        Args:\n            input: Documents or images to generate embeddings for.\n\n        Returns:\n            Embeddings for the documents.","sourceCodeStart":16,"sourceCodeEnd":52,"githubUrl":"https://github.com/chroma-core/chroma/blob/aecdd12c8a891610db8653630b066b32ceb678b5/chromadb/utils/embedding_functions/instructor_embedding_function.py#L16-L52","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","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"],"exampleFix":"# before\nfrom chromadb.utils import embedding_functions\nef = embedding_functions.InstructorEmbeddingFunction(model_name=\"hkunlp/instructor-base\")  # ValueError\n\n# after\n# pip install InstructorEmbedding\nimport importlib.util\nif importlib.util.find_spec(\"InstructorEmbedding\") is None:\n    raise SystemExit(\"pip install InstructorEmbedding\")\nef = embedding_functions.InstructorEmbeddingFunction(model_name=\"hkunlp/instructor-base\")","handlingStrategy":"validation","validationCode":"import importlib.util\n\nif importlib.util.find_spec(\"InstructorEmbedding\") is None:\n    raise SystemExit(\"Install optional dep: pip install InstructorEmbedding\")\n\nfrom chromadb.utils import embedding_functions\nef = embedding_functions.InstructorEmbeddingFunction(\n    model_name=\"hkunlp/instructor-base\", device=\"cpu\"\n)","typeGuard":null,"tryCatchPattern":"try:\n    ef = InstructorEmbeddingFunction(model_name=\"hkunlp/instructor-base\")\nexcept ValueError as e:\n    if \"InstructorEmbedding\" in str(e):\n        raise RuntimeError(\"pip install InstructorEmbedding\") from e\n    raise","preventionTips":["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"],"tags":["python","dependency","pip","instructor-embeddings","optional-import"],"backgroundTag":"missing-optional-dependency","analyzedSha":"aecdd12c8a891610db8653630b066b32ceb678b5","analyzedAt":"2026-08-16T21:53:27.228Z","schemaVersion":2},"datasetVersion":"2026-08-16T23:17:17.608Z"}