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`

What it means

OpenAIEmbeddingFunction.__init__ does `import openai` inside try/except ImportError and raises ValueError with the pip hint when the package is absent. The import is deferred to construction so chromadb works without the OpenAI SDK unless you use this EF. Right after this check, passing api_key directly triggers a DeprecationWarning directing you to api_key_env_var, and a preset OPENAI_API_KEY env var is picked up automatically.

Source

Thrown at chromadb/utils/embedding_functions/openai_embedding_function.py:49

            api_base (str, optional): The base path for the API. If not provided,
                it will use the base path for the OpenAI API. This can be used to
                point to a different deployment, such as an Azure deployment.
            api_type (str, optional): The type of the API deployment. This can be
                used to specify a different deployment, such as 'azure'. If not
                provided, it will use the default OpenAI deployment.
            api_version (str, optional): The api version for the API. If not provided,
                it will use the api version for the OpenAI API. This can be used to
                point to a different deployment, such as an Azure deployment.
            deployment_id (str, optional): Deployment ID for Azure OpenAI.
            default_headers (Dict[str, str], optional): A mapping of default headers to be sent with each API request.
            dimensions (int, optional): The number of dimensions for the embeddings.
                Only supported for `text-embedding-3` or later models from OpenAI.
                https://platform.openai.com/docs/api-reference/embeddings/create#embeddings-create-dimensions
        """
        try:
            import openai
        except ImportError:
            raise ValueError(
                "The openai python package is not installed. Please install it with `pip install openai`"
            )

        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,
            )

        if os.getenv("OPENAI_API_KEY") is not None:
            self.api_key_env_var = "OPENAI_API_KEY"
        else:
            self.api_key_env_var = api_key_env_var

        self.api_key = api_key or os.getenv(self.api_key_env_var)
        if not self.api_key:
            raise ValueError(

View on GitHub (pinned to aecdd12c8a)

Solutions

  1. pip install openai into the interpreter that runs Chroma (verify: python -m pip show openai)
  2. Add openai to requirements.txt/pyproject alongside chromadb
  3. While you're at it, prefer api_key_env_var="OPENAI_API_KEY" (default) over the deprecated direct api_key argument so the key is not persisted

Example fix

// before
fn = OpenAIEmbeddingFunction(model="text-embedding-3-small")  # ValueError: openai not installed

// after (shell)
pip install openai
// then
fn = OpenAIEmbeddingFunction(model="text-embedding-3-small")  # reads OPENAI_API_KEY from env
Defensive patterns

Strategy: validation

Validate before calling

import importlib.util, os
if importlib.util.find_spec("openai") is None:
    raise SystemExit("openai package missing: pip install openai")
if not os.getenv("OPENAI_API_KEY"):
    raise SystemExit("OPENAI_API_KEY not set")
fn = OpenAIEmbeddingFunction(model="text-embedding-3-small")

Try / catch

try:
    fn = OpenAIEmbeddingFunction(model="text-embedding-3-small")
except ValueError as e:
    if "openai" in str(e) and "not installed" in str(e):
        raise SystemExit("Run: pip install openai") from e
    raise

Prevention

When it happens

Trigger: Constructing OpenAIEmbeddingFunction(api_key_env_var=...) or with OPENAI_API_KEY set, in an environment where `pip install openai` was never run; venv mismatch; installing openai into a notebook kernel env but running the app elsewhere; fresh CI image with only chromadb.

Common situations: Local dev works, CI/deploy fails (openai not in requirements.txt); switching from API-key-arg to env-var configuration mid-project and reinstalling deps incompletely; Python version upgrade where openai wheels (needs >=3.7 for v1) failed to install.

Related errors

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