Install & Compatibility
Where this runs
tested against v1.3.0 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslpy 3.10–3.95 runs
installs and imports cleanly · install 0.0s · import 5.706s · 107.5MB
glibcpy 3.10–3.95 runs
installs and imports cleanly · install 12.3s · import 5.306s · 118MB
112MB installed
● package 112MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
ChatXAI
✓ from langchain_xai import ChatXAI
✗ from langchain.chat_models import ChatXAI
As a partner integration, ChatXAI is imported directly from its dedicated package, not from the top-level langchain.chat_models module.
This example demonstrates how to initialize the `ChatXAI` model, pass messages, and invoke it to get a response. It also shows how to stream responses. Ensure your `XAI_API_KEY` is set as an environment variable or passed directly to the `ChatXAI` constructor.
import os
from langchain_xai import ChatXAI
from langchain_core.messages import HumanMessage, SystemMessage
# Set your xAI API key as an environment variable (e.g., in your shell: export XAI_API_KEY="YOUR_API_KEY")
# Or pass it directly as xai_api_key="YOUR_API_KEY" to ChatXAI
api_key = os.environ.get("XAI_API_KEY", "YOUR_XAI_API_KEY_HERE") # Replace with actual key or ensure env var is set
if api_key == "YOUR_XAI_API_KEY_HERE":
print("Warning: XAI_API_KEY not found in environment variables. Please set it or pass it directly.")
print("Skipping example due to missing API key.")
else:
model = ChatXAI(
model="grok-4",
temperature=0,
xai_api_key=api_key # Pass the API key
)
messages = [
SystemMessage(content="You are a helpful assistant."),
HumanMessage(content="What is the capital of France?"),
]
print("Invoking Grok model...")
response = model.invoke(messages)
print(response.content)
print("\nStreaming response:")
for chunk in model.stream(messages):
print(chunk.content, end="")
print()
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'langchain_xai'
This error occurs when the `langchain-xai` package is not installed or incorrectly imported, often due to confusion with the older monolithic `langchain` package structure or a separate JavaScript package.
fixEnsure the `langchain-xai` package is installed using `pip install -U langchain-xai` and that `ChatXAI` is imported from `langchain_xai` (e.g., `from langchain_xai import ChatXAI`).
ValueError: Invalid API key
This error typically arises when the `XAI_API_KEY` is not correctly set as an environment variable or passed explicitly during the `ChatXAI` model instantiation, preventing authentication with the xAI API.
fixSet the `XAI_API_KEY` environment variable (e.g., `export XAI_API_KEY="your_key_here"` in your terminal or `os.environ["XAI_API_KEY"] = "your_key_here"` in Python) or pass it directly to the `ChatXAI` constructor: `ChatXAI(xai_api_key="your_key_here", ...)`.
{'error': 'Live search is deprecated. Please switch to the Agent Tools API: https://docs.x.ai/docs/guides/tools/overview'}
This specific error message is returned by the xAI API when attempting to use the older 'Live Search' feature, which has been deprecated in favor of the newer Agent Tools API.
fixUpdate your code to use the Agent Tools API for search functionalities as recommended by xAI. The `langchain-xai` integration should be updated to leverage the new tool-calling mechanisms.
Error code: 400 - {'code': 'Client specified an invalid argument', 'error': 'Invalid request content: Each message must have at least one content element.'}
This 400 error occurs when sending an `AIMessage` with `tool_calls` but an empty or null `content` field to the xAI Grok model, as xAI's API is stricter and requires all messages to have at least one content element.
fixEnsure that `AIMessage` objects always have a `content` field, even if it's an empty string, when `tool_calls` are present. A common workaround involves subclassing `ChatXAI` to sanitize messages before sending them.
Argument not supported on this model: presencePenalty
This error indicates that a specific parameter, such as `presencePenalty` (or similar model-tuning parameters), is not supported by the particular xAI Grok model version you are using.
fixRemove or adjust the unsupported parameter from your `ChatXAI` instantiation or method call. Consult the xAI model documentation for the specific parameters supported by your chosen Grok model version.
Upgrade
Version history
1.3.0latest on PyPI · released Jul 21, 2026
Audit
Dependencies
langchain-corerequiredCore LangChain functionalities and base abstractions.
aiohttprequiredAsynchronous HTTP client for network requests.
requestsrequiredSynchronous HTTP client for network requests.