OpenAI Integration for LangChain

raw JSON →
1.1.12 verified Tue May 12 auth: no python install: verified quickstart: verified

An integration package connecting OpenAI and LangChain, providing classes for chat models (`ChatOpenAI`) and embeddings (`OpenAIEmbeddings`). It is actively maintained with frequent releases, typically minor versions every few months and patch releases more frequently, as part of the broader LangChain ecosystem.

pip install langchain-openai

Common errors

error ModuleNotFoundError: No module named 'langchain_openai' ↓
cause The `langchain-openai` integration package is not installed in your Python environment. It's a separate package and not automatically included with `langchain` itself.
fix
Install the package using pip: pip install langchain-openai
error AuthenticationError: Incorrect API key provided: sk-... ↓
cause The OpenAI API key is either missing, incorrect, expired, or not accessible in the environment where `langchain-openai` is trying to use it. This often happens if the `OPENAI_API_KEY` environment variable is not set or is set with an invalid key, or if the key is hardcoded incorrectly.
fix
Ensure your OpenAI API key is correctly set as an environment variable named OPENAI_API_KEY (e.g., export OPENAI_API_KEY="your_key_here" in your shell, or in a .env file loaded with python-dotenv). Alternatively, pass it directly to the ChatOpenAI or OpenAIEmbeddings constructor: ChatOpenAI(api_key="your_key_here").
error ValidationError: 1 validation error for ChatOpenAI __root__ `openai` has no `ChatCompletion` attribute, this is likely due to an old version of the openai package. Try upgrading it with `pip install --upgrade openai`. ↓
cause You are likely using an outdated version of the `openai` Python library (older than 1.0.0) which is incompatible with the version of `langchain-openai` you have installed. The `openai` library underwent a major refactor in version 1.0.0.
fix
Upgrade your openai package to the latest version: pip install --upgrade openai. Ensure langchain-openai is also up-to-date: pip install --upgrade langchain-openai.
error ImportError: cannot import name 'ChatOpenAI' from partially initialized module 'langchain_openai' (most likely due to a circular import) ↓
cause This specific error often occurs when you have a local Python file named `openai.py` in your project directory. Python's import mechanism prioritizes local files, causing it to try and import from your `openai.py` instead of the installed `openai` package, leading to a circular import when `langchain_openai` tries to import `openai`.
fix
Rename your local openai.py file to something else (e.g., my_openai_utils.py) to avoid conflicts with the official openai package.

Warnings

breaking LangChain v1 introduced a new package structure. Most OpenAI-related classes moved from the monolithic `langchain` package (e.g., `langchain.chat_models.ChatOpenAI`) to the dedicated `langchain-openai` partner package (e.g., `langchain_openai.ChatOpenAI`). Code using old import paths will break. ↓
fix Update import statements from `from langchain...` to `from langchain_openai...` for OpenAI-specific components like `ChatOpenAI` and `OpenAIEmbeddings`.
gotcha Compatibility with `langchain-core` is crucial. The `langchain-openai` package frequently bumps its minimum required `langchain-core` version. Running `langchain-openai` with an outdated `langchain-core` can lead to `AttributeError`s or unexpected behavior due to schema drifts or missing fields. [cite: 1.1.12 release notes] ↓
fix Always ensure `langchain-core` is up-to-date by running `pip install -U langchain-openai langchain-core`.
breaking For Azure OpenAI, `ChatOpenAI` now supports the v1 API directly using `base_url` and `api_key` parameters since `langchain-openai>=1.0.1`. The legacy `AzureChatOpenAI` class is still available but `ChatOpenAI` is the recommended unified approach for the v1 API. ↓
fix For new Azure OpenAI integrations, use `langchain_openai.ChatOpenAI` with `base_url` set to your Azure endpoint (e.g., `https://{your-resource-name}.openai.azure.com/openai/v1/`) and provide the `api_key`. Migrate existing `AzureChatOpenAI` usage if a unified interface is desired.
gotcha When using `OpenAIEmbeddings` with non-OpenAI compatible APIs (e.g., OpenRouter, Ollama, vLLM via `base_url`), the default `check_embedding_ctx_length` might cause errors. ↓
fix Set `check_embedding_ctx_length=False` in the `OpenAIEmbeddings` constructor (e.g., `OpenAIEmbeddings(model="your-model", base_url="https://your-api-endpoint.com", check_embedding_ctx_length=False)`).
deprecated When interacting with the OpenAI Responses API, `langchain-openai` now defaults to storing response items in message content. To restore the previous (v0) behavior, users need to explicitly opt-in. ↓
fix Set the `LC_OUTPUT_VERSION` environment variable to `v0` or specify `output_version="v0"` when instantiating `ChatOpenAI` (e.g., `ChatOpenAI(model="gpt-4o-mini", output_version="v0")`).
breaking OpenAI API calls require an API key for authentication. This key must be provided either as an environment variable (e.g., `OPENAI_API_KEY`) or directly as an `api_key` parameter when instantiating `ChatOpenAI` or `OpenAIEmbeddings`. Failure to provide an API key results in an `AuthenticationError`. ↓
fix Ensure the `OPENAI_API_KEY` environment variable is set with a valid OpenAI API key, or pass `api_key='your_key'` to the constructor of `ChatOpenAI` or `OpenAIEmbeddings`.
breaking OpenAI API calls require an API key for authentication. If an API key is not provided (either via the `OPENAI_API_KEY` environment variable or explicitly in the model constructor), an `AuthenticationError` will occur, preventing any API interaction. ↓
fix Ensure the `OPENAI_API_KEY` environment variable is set, or pass the `api_key` argument directly to the `ChatOpenAI` or `OpenAI` model constructor (e.g., `ChatOpenAI(model="gpt-4", api_key="YOUR_API_KEY")`).

Install compatibility verified last tested: 2026-05-12

python os / libc status wheel install import disk
3.10 alpine (musl) wheel - 3.83s 87.9M
3.10 alpine (musl) - - 3.76s 84.9M
3.10 slim (glibc) wheel 10.0s 2.85s 96M
3.10 slim (glibc) - - 2.71s 93M
3.11 alpine (musl) wheel - 4.62s 94.7M
3.11 alpine (musl) - - 5.05s 91.4M
3.11 slim (glibc) wheel 8.8s 4.27s 103M
3.11 slim (glibc) - - 4.02s 100M
3.12 alpine (musl) wheel - 4.17s 85.3M
3.12 alpine (musl) - - 4.48s 82.1M
3.12 slim (glibc) wheel 7.1s 4.24s 94M
3.12 slim (glibc) - - 4.71s 90M
3.13 alpine (musl) wheel - 3.98s 85.1M
3.13 alpine (musl) - - 4.19s 81.7M
3.13 slim (glibc) wheel 7.3s 4.12s 93M
3.13 slim (glibc) - - 4.33s 90M
3.9 alpine (musl) wheel - 3.74s 84.4M
3.9 alpine (musl) - - 3.48s 82.3M
3.9 slim (glibc) wheel 11.2s 3.41s 92M
3.9 slim (glibc) - - 3.10s 90M

Imports

Quickstart verified last tested: 2026-04-24

This quickstart demonstrates how to initialize `ChatOpenAI` and send a basic message. It assumes the `OPENAI_API_KEY` environment variable is set.

import os
from langchain_openai import ChatOpenAI
from langchain_core.messages import HumanMessage

# Set your OpenAI API key as an environment variable (recommended)
# Or pass it directly: ChatOpenAI(openai_api_key="your_api_key")

# Ensure OPENAI_API_KEY is set in your environment
if not os.environ.get("OPENAI_API_KEY"): 
    os.environ["OPENAI_API_KEY"] = os.environ.get("OPENAI_API_KEY", "") # Replace with actual key or prompt user
    # For interactive use, you might use: 
    # import getpass 
    # os.environ["OPENAI_API_KEY"] = getpass.getpass("Enter your OpenAI API key: ")

# Instantiate the ChatOpenAI model
chat_model = ChatOpenAI(model="gpt-4o-mini", temperature=0.7)

# Invoke the model
response = chat_model.invoke([HumanMessage(content="Tell me a short story about a brave knight.")])

print(response.content)
last verified Tue May 12
next check Fri Jun 26