{"record":{"id":"4279162cf00cc61d","repo":"chroma-core/chroma","slug":"the-openai-python-package-is-not-installed-please-427916","errorCode":null,"errorMessage":"The openai python package is not installed. Please install it with `pip install openai`","messagePattern":"The openai python package is not installed\\. Please install it with `pip install openai`","errorType":"exception","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"chromadb/utils/embedding_functions/openai_embedding_function.py","lineNumber":49,"sourceCode":"            api_base (str, optional): The base path for the API. If not provided,\n                it will use the base path for the OpenAI API. This can be used to\n                point to a different deployment, such as an Azure deployment.\n            api_type (str, optional): The type of the API deployment. This can be\n                used to specify a different deployment, such as 'azure'. If not\n                provided, it will use the default OpenAI deployment.\n            api_version (str, optional): The api version for the API. If not provided,\n                it will use the api version for the OpenAI API. This can be used to\n                point to a different deployment, such as an Azure deployment.\n            deployment_id (str, optional): Deployment ID for Azure OpenAI.\n            default_headers (Dict[str, str], optional): A mapping of default headers to be sent with each API request.\n            dimensions (int, optional): The number of dimensions for the embeddings.\n                Only supported for `text-embedding-3` or later models from OpenAI.\n                https://platform.openai.com/docs/api-reference/embeddings/create#embeddings-create-dimensions\n        \"\"\"\n        try:\n            import openai\n        except ImportError:\n            raise ValueError(\n                \"The openai python package is not installed. Please install it with `pip install openai`\"\n            )\n\n        if api_key is not None:\n            warnings.warn(\n                \"Direct api_key configuration will not be persisted. \"\n                \"Please use environment variables via api_key_env_var for persistent storage.\",\n                DeprecationWarning,\n            )\n\n        if os.getenv(\"OPENAI_API_KEY\") is not None:\n            self.api_key_env_var = \"OPENAI_API_KEY\"\n        else:\n            self.api_key_env_var = api_key_env_var\n\n        self.api_key = api_key or os.getenv(self.api_key_env_var)\n        if not self.api_key:\n            raise ValueError(","sourceCodeStart":31,"sourceCodeEnd":67,"githubUrl":"https://github.com/chroma-core/chroma/blob/aecdd12c8a891610db8653630b066b32ceb678b5/chromadb/utils/embedding_functions/openai_embedding_function.py#L31-L67","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["pip install openai into the interpreter that runs Chroma (verify: python -m pip show openai)","Add openai to requirements.txt/pyproject alongside chromadb","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"],"exampleFix":"// before\nfn = OpenAIEmbeddingFunction(model=\"text-embedding-3-small\")  # ValueError: openai not installed\n\n// after (shell)\npip install openai\n// then\nfn = OpenAIEmbeddingFunction(model=\"text-embedding-3-small\")  # reads OPENAI_API_KEY from env","handlingStrategy":"validation","validationCode":"import importlib.util, os\nif importlib.util.find_spec(\"openai\") is None:\n    raise SystemExit(\"openai package missing: pip install openai\")\nif not os.getenv(\"OPENAI_API_KEY\"):\n    raise SystemExit(\"OPENAI_API_KEY not set\")\nfn = OpenAIEmbeddingFunction(model=\"text-embedding-3-small\")","typeGuard":null,"tryCatchPattern":"try:\n    fn = OpenAIEmbeddingFunction(model=\"text-embedding-3-small\")\nexcept ValueError as e:\n    if \"openai\" in str(e) and \"not installed\" in str(e):\n        raise SystemExit(\"Run: pip install openai\") from e\n    raise","preventionTips":["Add openai to the same lockfile as chromadb when using this EF","Prefer api_key_env_var (default OPENAI_API_KEY) over the deprecated direct api_key arg","Run a startup check that imports openai and verifies the env key exists"],"tags":["openai","embedding-function","import-error","dependency","chroma"],"backgroundTag":"missing-dependency","analyzedSha":"aecdd12c8a891610db8653630b066b32ceb678b5","analyzedAt":"2026-08-16T21:53:27.228Z","schemaVersion":2},"datasetVersion":"2026-08-16T23:17:17.608Z"}