chroma-core/chroma · error · ValueError

The openai python package is not installed. Please install i

Error message

The openai python package is not installed. Please install it with `pip install openai`. Note: Morph uses the OpenAI client library for API communication.

What it means

MorphEmbeddingFunction uses the OpenAI python client pointed at Morph's base URL (https://api.morphllm.com/v1), importing openai lazily in __init__. If the openai package is absent, the ImportError becomes this ValueError at construction — the message explicitly notes Morph rides on the OpenAI client library. openai is optional in chromadb installs.

Source

Thrown at chromadb/utils/embedding_functions/morph_embedding_function.py:36

        """
        Initialize the MorphEmbeddingFunction.

        Args:
            api_key (str, optional): The API key for the Morph API. If not provided,
                it will be read from the environment variable specified by api_key_env_var.
            model_name (str, optional): The name of the model to use for embeddings.
                Defaults to "morph-embedding-v2".
            api_base (str, optional): The base URL for the Morph API.
                Defaults to "https://api.morphllm.com/v1".
            encoding_format (str, optional): The format for embeddings (float or base64).
                Defaults to "float".
            api_key_env_var (str, optional): Environment variable name that contains your API key.
                Defaults to "MORPH_API_KEY".
        """
        try:
            import openai
        except ImportError:
            raise ValueError(
                "The openai python package is not installed. Please install it with `pip install openai`. "
                "Note: Morph uses the OpenAI client library for API communication."
            )

        if api_key is not None:
            warnings.warn(
                "Direct api_key configuration will not be persisted. "
                "Please use environment variables via api_key_env_var for persistent storage.",
                DeprecationWarning,
            )

        self.api_key_env_var = api_key_env_var
        self.api_key = api_key or os.getenv(api_key_env_var)
        if not self.api_key:
            raise ValueError(f"The {api_key_env_var} environment variable is not set.")

        self.model_name = model_name
        self.api_base = api_base

View on GitHub (pinned to aecdd12c8a)

Solutions

pip install openai
Verify: python -c "import openai; print(openai.__version__)"
Pin openai in requirements so future syncs keep it

Example fix

# before
from chromadb.utils.embedding_functions import MorphEmbeddingFunction
ef = MorphEmbeddingFunction()  # ValueError: openai missing

# after
# pip install openai
import importlib.util
if importlib.util.find_spec("openai") is None:
    raise SystemExit("pip install openai")
ef = MorphEmbeddingFunction()

Defensive patterns

Strategy: validation

Validate before calling

import importlib.util

if importlib.util.find_spec("openai") is None:
    raise SystemExit("Morph EF rides on the OpenAI client: pip install openai")

from chromadb.utils.embedding_functions import MorphEmbeddingFunction
ef = MorphEmbeddingFunction()

Try / catch

try:
    ef = MorphEmbeddingFunction()
except ValueError as e:
    if "openai" in str(e):
        raise RuntimeError("pip install openai") from e
    raise

Prevention

Remember Morph requires the openai package even though it is not OpenAI's API
Declare openai explicitly in requirements when enabling the Morph EF
Preflight find_spec checks per configured EF at app start

When it happens

Trigger: MorphEmbeddingFunction(model_name='morph-embedding-v2') in an environment that never installed openai; slim containers; envs where openai was uninstalled after another EF stopped needing it.

Common situations: Switching a project from a no-openai setup to the Morph EF; CI environments caching partial installs; local venvs created before Morph integration was added.

Related errors

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