Install & Compatibility
Where this runs
tested against v1.1.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
py 3.9
✕ build_error
✕ build_error
251MB installed
● package 251MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
ChatWatsonx
✓ from langchain_ibm import ChatWatsonx
WatsonxLLM
✓ from langchain_ibm import WatsonxLLM
WatsonxEmbeddings
✓ from langchain_ibm import WatsonxEmbeddings
WatsonxRerank
✓ from langchain_ibm import WatsonxRerank
TextChatParameters
✓ from ibm_watsonx_ai.foundation_models.schema import TextChatParameters
Required for configuring ChatWatsonx models.
TextGenParameters
✓ from ibm_watsonx_ai.foundation_models.schema import TextGenParameters
Required for configuring WatsonxLLM models.
This quickstart demonstrates how to initialize and use the `ChatWatsonx` model. It requires an IBM Cloud API key and a watsonx.ai Project ID, which should be set as environment variables for security. You also need to specify a `model_id` and the appropriate `url` for your watsonx.ai service instance.
import os
from getpass import getpass
from langchain_ibm import ChatWatsonx
from ibm_watsonx_ai.foundation_models.schema import TextChatParameters
# Set environment variables (replace with your actual values or retrieve from a secure source)
if not os.environ.get("WATSONX_API_KEY"): os.environ["WATSONX_API_KEY"] = getpass("Enter your IBM Cloud API Key: ")
if not os.environ.get("WATSONX_PROJECT_ID"): os.environ["WATSONX_PROJECT_ID"] = getpass("Enter your IBM watsonx.ai Project ID: ")
# Define model parameters
parameters = TextChatParameters(
temperature=0.7,
max_completion_tokens=500
)
# Initialize the ChatWatsonx model
# Replace with your actual model_id and url
model = ChatWatsonx(
model_id="ibm/granite-13b-chat-v2",
url="https://us-south.ml.cloud.ibm.com", # Example URL, choose based on your region
project_id=os.environ["WATSONX_PROJECT_ID"],
params=parameters,
)
# Invoke the model
response = model.invoke("What is the capital of France?")
print(response.content)
Debug
Known issues
breakingLangChain v1 introduced significant changes to package namespaces and import paths within the core LangChain library. If you are migrating from an older LangChain version, ensure your `langchain-core` dependency is compatible and update imports accordingly, as older tutorials may break.fixUpgrade `langchain-core` to a compatible version (>=1.0.0 for LangChain v1) and review LangChain's official migration guides for updated import paths and API changes. Check `langchain-ibm` release notes for specific `langchain-core` version requirements.
affects: LangChain core < 1.0.0 (and dependent langchain-ibm versions)
gotchaIBM watsonx.ai models require an API key and Project ID, which should ideally be set as environment variables (e.g., `WATSONX_API_KEY`, `WATSONX_PROJECT_ID`) rather than hardcoding. Also, the `model_id` and `url` must be correctly specified for your watsonx.ai service instance.fixSet `WATSONX_API_KEY` and `WATSONX_PROJECT_ID` environment variables. Ensure `model_id` and `url` parameters are accurate for your chosen watsonx.ai model and region during model initialization.
affects: All
gotchaDifferent watsonx.ai model types (chat, LLM, reranker) require specific parameter schemas (e.g., `TextChatParameters` for `ChatWatsonx`, `TextGenParameters` for `WatsonxLLM`, `RerankParameters` for `WatsonxRerank`). Using the wrong schema will lead to errors.fixImport and use the correct parameter schema class from `ibm_watsonx_ai.foundation_models.schema` corresponding to the LangChain-IBM model wrapper you are initializing.
affects: All
breakingA serialization injection vulnerability (CVE-2025-68664) was found in LangChain's `dumps()` and `dumpd()` functions, allowing untrusted data with 'lc' keys to be deserialized as objects. This directly affects `langchain-core` versions and, by extension, applications using `langchain-ibm` that rely on these serialization methods.fixUpgrade `langchain-core` to version 0.3.81 / 1.2.5 or higher. Ensure any downstream IBM products like `watsonx.data` are also updated to their latest patched versions (e.g., `watsonx.data 2.3.1` or `watsonx.data on CPD 5.3.1`).
affects: langchain-core versions prior to 0.3.81 and 1.2.5
gotchaThere is an open bug where `asyncio` calls may fail due to synchronous, connection-pooled HTTP clients in the underlying `ibm-watsonx-ai` SDK. This can lead to unexpected behavior or deadlocks in asynchronous applications.fixMonitor the `langchain-ibm` GitHub repository for updates and patches related to issue #83. Consider using synchronous calls or implementing workarounds if asynchronous operations are critical and exhibit this behavior.
affects: All known versions, issue #83 is open on GitHub.
Upgrade
Version history
1.1.0latest on PyPI · released Jun 3, 2026
Audit
Dependencies
ibm-watsonx-airequiredCore SDK for interacting with IBM watsonx.ai services.
json-repairrequiredUsed for repairing malformed JSON output.
langchain-corerequiredProvides core LangChain functionalities and base classes.
pyarrowoptionalOptional dependency for the SQL database toolkit.