Install & Compatibility
Where this runs
tested against v0.7.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 9.734s · 319MB
glibcpy 3.10–3.95 runs
installs and imports cleanly · install 22.0s · import 9.478s · 310MB
307MB installed
● package 307MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
ChatLiteLLM
✓ from langchain_litellm import ChatLiteLLM
ChatLiteLLMRouter
✓ from langchain_litellm import ChatLiteLLMRouter
LiteLLMEmbeddings
✓ from langchain_litellm import LiteLLMEmbeddings
LiteLLMEmbeddingsRouter
✓ from langchain_litellm import LiteLLMEmbeddingsRouter
LiteLLMOCRLoader
✓ from langchain_litellm import LiteLLMOCRLoader
This quickstart demonstrates how to instantiate and use ChatLiteLLM for basic chat completions and LiteLLMEmbeddings for text embedding. Ensure the relevant API key (e.g., OPENAI_API_KEY) is set in your environment or passed directly to the constructor. The `model` parameter should specify the desired LLM provider and model in LiteLLM's unified format.
import os
from langchain_litellm import ChatLiteLLM
from langchain_core.messages import HumanMessage
# Set your API key for LiteLLM's underlying provider (e.g., OpenAI)
# For a real application, use a secure method to manage API keys.
os.environ["OPENAI_API_KEY"] = os.environ.get("OPENAI_API_KEY", "sk-your-openai-key")
# Instantiate ChatLiteLLM, specifying the model in LiteLLM's format
# (e.g., 'openai/gpt-3.5-turbo' for OpenAI)
chat_model = ChatLiteLLM(model="openai/gpt-3.5-turbo")
# Invoke the chat model
response = chat_model.invoke([HumanMessage(content="Hello, how are you?")])
print(response.content)
# Example for LiteLLMEmbeddings
from langchain_litellm import LiteLLMEmbeddings
# Note: API key can be passed explicitly if not in environment for embeddings
embeddings = LiteLLMEmbeddings(
model="openai/text-embedding-3-small",
api_key=os.environ.get("OPENAI_API_KEY", "sk-your-openai-key")
)
text = "This is a test document."
embedding = embeddings.embed_query(text)
print(f"Embedding length: {len(embedding)}")
Debug
Known issues
breakingCritical supply chain attack on `litellm` (versions 1.82.7 and 1.82.8) in March 2026. These versions contained credential-stealing malware. `langchain-litellm` version 0.6.2 and above explicitly excludes these compromised `litellm` versions from its dependencies.fixUpgrade `langchain-litellm` to v0.6.2 or later (`pip install -U langchain-litellm`) to ensure malicious `litellm` versions are excluded. Always pin `litellm` and `langchain-litellm` versions in production environments (`litellm==x.y.z`, `langchain-litellm==a.b.c`) and review dependencies.
affects: litellm==1.82.7, litellm==1.82.8 (indirectly via older langchain-litellm versions)
gotchaWhen using Claude models, `tool_choice` might be automatically downgraded to `auto` if 'thinking' is enabled. This can alter expected tool-use behavior.fixReview the specific behavior with Claude models and tool calling if 'thinking' is enabled. Test tool invocation carefully after upgrading to v0.6.4.
affects: v0.6.4 and later
gotchaA common error is `litellm.BadRequestError: LLM Provider NOT provided`. This occurs when the underlying LLM provider for LiteLLM is not correctly specified or configured, often due to missing `model` parameters or incorrect API key environment variables.fixEnsure the `model` parameter is correctly formatted (e.g., `openai/gpt-3.5-turbo`, `anthropic/claude-3-opus-20240229`) and the corresponding API key (e.g., `OPENAI_API_KEY`, `ANTHROPIC_API_KEY`) is set in environment variables or passed explicitly.
affects: All versions
gotchaIntegrating `langchain-litellm` with a LiteLLM Proxy often requires special handling for authentication headers (e.g., `Authorization: Bearer <token>`). LangChain's internal HTTP request mechanisms might not easily expose the ability to inject these custom headers, leading to integration difficulties.fixConsult LiteLLM's documentation on proxy usage and `langchain-litellm`'s specific configurations for connecting to a proxy. You might need to configure LiteLLM directly or wrap the `ChatLiteLLM` instance with custom HTTP client logic.
affects: All versions
gotchaVersion `0.6.4` included a fix to `extract reasoning tokens and handle pydantic usage in metadata`. This could imply subtle changes or sensitivities related to Pydantic versions and how structured outputs or metadata are processed, which is a frequent source of issues in the LangChain ecosystem.fixEnsure your environment's Pydantic version is compatible. If encountering issues with structured outputs or metadata handling, specifically review changes in `v0.6.4` related to Pydantic and update your code accordingly.
affects: Potentially affects applications relying on specific Pydantic behavior with metadata prior to v0.6.4.
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'langchain.chat_models'
This error occurs because of changes in LangChain's modularization, where `ChatLiteLLM` was moved from the `langchain` package to `langchain_community` or directly to `langchain_litellm` in newer versions.
fixUpdate your import statement to use `from langchain_community.chat_models import ChatLiteLLM` or `from langchain_litellm import ChatLiteLLM` depending on your LangChain installation and package structure. Ensure `langchain-litellm` is installed via `pip install -U langchain-litellm`.
AttributeError: 'dict' object has no attribute 'role' (when streaming=True with ChatLiteLLM)
This issue typically arises in older versions of `langchain_litellm` (e.g., 0.2.1) when `streaming=True` is used. The `_convert_delta_to_message_chunk` function expects a delta object with a 'role' attribute, but sometimes receives a dictionary instead, leading to this error.
fixUpgrade `langchain-litellm` to its latest version (0.6.4 or newer) using `pip install -U langchain-litellm` to resolve this incompatibility.
litellm.BadRequestError: LLM Provider NOT provided. Pass in the LLM provider you are trying to call
This error from LiteLLM (which `langchain-litellm` wraps) indicates that the model name provided does not specify which LLM provider to use. LiteLLM requires a explicit provider prefix for most models.
fixPrefix your model name with the corresponding LLM provider, for example, `model="openai/gpt-4"`, `model="anthropic/claude-3-opus"`, or `model="gemini/gemini-1.5-flash"` for Google AI Studio models.
Unable to use Langchain with LiteLLM proxy (authentication headers not passed)
When using `ChatLiteLLM` with a LiteLLM proxy that requires custom HTTP headers (like `Authorization: Bearer <token>`), LangChain's `ChatLiteLLM` might not inherently pass these headers through its default constructor arguments.
fixPass the required headers through the `model_kwargs` parameter of `ChatLiteLLM`, for example: `chat = ChatLiteLLM(model='litellm_proxy/gpt-3.5-turbo', api_base='http://your-litellm-proxy-url', model_kwargs={'headers': {'Authorization': 'Bearer YOUR_PROXY_KEY'}})`. Upgrade
Version history
0.7.0latest on PyPI · released Jun 15, 2026
Audit
Dependencies
pythonrequiredRequired Python version range
langchainrequiredCore LangChain framework dependency
litellmrequiredCore LiteLLM library dependency for LLM unification