Install & Compatibility
Where this runs
tested against v1.3.42 · 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
200MB installed
● package 200MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
APIClient
✓ from ibm_watsonx_ai import APIClient
Credentials
✓ from ibm_watsonx_ai import Credentials
Model
✓ from ibm_watsonx_ai.foundation_models import Model
ModelTypes
✓ from ibm_watsonx_ai.foundation_models.utils.enums import ModelTypes
DecodingMethods
✓ from ibm_watsonx_ai.foundation_models.utils.enums import DecodingMethods
This quickstart demonstrates how to authenticate with the `ibm-watsonx-ai` SDK using environment variables and perform a basic text generation task with a foundation model. Ensure your `IBM_CLOUD_API_KEY`, `WATSONX_AI_URL`, and `WATSONX_PROJECT_ID` environment variables are set.
import os
from ibm_watsonx_ai import APIClient, Credentials
from ibm_watsonx_ai.foundation_models import Model
from ibm_watsonx_ai.foundation_models.utils.enums import ModelTypes, DecodingMethods
# --- Authentication ---
# Set these environment variables: IBM_CLOUD_API_KEY, WATSONX_AI_URL, WATSONX_PROJECT_ID
api_key = os.environ.get("IBM_CLOUD_API_KEY", "")
watsonx_url = os.environ.get("WATSONX_AI_URL", "https://us-south.ml.cloud.ibm.com")
project_id = os.environ.get("WATSONX_PROJECT_ID", "")
if not all([api_key, watsonx_url, project_id]):
raise ValueError("Please set IBM_CLOUD_API_KEY, WATSONX_AI_URL, and WATSONX_PROJECT_ID environment variables.")
credentials = Credentials(
api_key=api_key,
url=watsonx_url
)
client = APIClient(credentials)
client.set.default_project(project_id)
print(f"Authenticated successfully for project_id: {project_id}")
# --- Foundation Model Inference (Text Generation) ---
model_id = ModelTypes.GRANITE_13B_INSTRUCT.value # Or other supported model like MISTRAL_7B_INSTRUCT
# Model parameters for text generation
parameters = {
"decoding_method": DecodingMethods.GREEDY,
"max_new_tokens": 50,
"min_new_tokens": 1,
"stop_sequences": []
}
# Initialize the model object
model = Model(
model_id=model_id,
credentials=credentials,
project_id=project_id,
parameters=parameters
)
# Define the prompt
prompt = "Write a short poem about artificial intelligence:"
# Generate text
try:
print(f"\nPrompt: {prompt}")
generated_text = model.generate_text(prompt=prompt)
print(f"Generated Text:\n{generated_text}")
except Exception as e:
print(f"An error occurred during text generation: {e}")
Debug
Known issues
breakingThe `client.<resource>.list()` methods no longer directly print a table of assets. Instead, they now return a `pandas.DataFrame` object. The `return_as_df` optional parameter has been removed as it is now the default and only behavior.fixUpdate your code to expect a `pandas.DataFrame` from `.list()` methods. Process the returned DataFrame directly instead of relying on printed output.
affects: Likely V1 and newer, check documentation for specific exact version transition.
breakingPrompt tuning as a method to tune foundation models is no longer supported and all existing prompt tuning deployments will be removed upon upgrading the `watsonx.ai` service. Parameter-efficient fine-tuning (PEFT) techniques like LoRA and QLoRA are now the recommended alternatives.fixMigrate existing prompt tuning deployments to alternative tuning methods, such as LoRA or QLoRA, which are available programmatically. Refer to the official `watsonx.ai` documentation for guidance on new tuning approaches.
affects: From February 2025 releases (IBM Software Hub 5.1.1) and newer.
deprecatedSeveral foundation models are regularly deprecated and eventually withdrawn. For example, `pixtral-12b` was deprecated in a recent release, and models like `codestral-22b`, `llama-2-13b-chat`, `mistral-small-instruct`, `mistral-large`, and `mixtral-8x7b-instruct-v01` were deprecated in the August 2025 release (IBM Software Hub 5.2.1). Older versions of IBM foundation models remain available for at least 90 days after an update.fixReview your application's use of foundation models. If you are using a deprecated model, migrate to a recommended alternative listed in the `watsonx.ai` documentation. IBM regularly updates its list of supported models.
affects: Ongoing, check 'What's new and changed in watsonx.ai' documentation for specific model lifecycles.
gotchaFor most operations, setting a default `project_id` or `space_id` using `client.set.default_project()` or `client.set.default_space()` is mandatory after initializing `APIClient`. Failure to do so will result in errors.fixAlways call `client.set.default_project(your_project_id)` or `client.set.default_space(your_space_id)` after creating the `APIClient` instance, unless you are specifically using a lightweight engine which does not require it.
affects: All versions.
gotchaWhen importing PyTorch models into `watsonx.ai`, they must first be exported to the `.onnx` format. Direct import of other PyTorch model formats is not supported.fixBefore attempting to import a PyTorch model, ensure it has been converted and exported to the `.onnx` format using `torch.onnx.export()`.
affects: All versions.
Errors
Common errors & fixes
401 error
The API key, IAM token, or project ID provided for authentication is incorrect, expired, or lacks the necessary permissions, or the associated Watson Machine Learning (WML) service instance is inactive or not correctly linked to the project.
fixVerify that your API key or IAM token is valid and active, ensure the `project_id` matches your watsonx.ai project, and confirm that the watsonx.ai Runtime service instance is correctly associated with your project by re-associating it if necessary.
ModuleNotFoundError: No module named 'unitxt'
The `unitxt` library, which is required for evaluating patterns in AutoAI Retrieval-Augmented Generation (RAG) experiments, is not installed in the Python environment by default.
fixInstall the required `unitxt` library using pip: `pip install unitxt==1.14.0`.
Failed to deploy the custom foundation model. The operation failed due to 'max_batch_weight (xxx) not large enough for (prefill) max_sequence_length (yyy)'
The `max_sequence_length` or `max_new_token` parameters configured for a custom foundation model deployment exceed the model's or the system's capacity, leading to an out-of-memory or resource allocation failure during prefill.
fixReduce the values for `max_sequence_length` and `max_new_tokens` in your model deployment configuration to be within the acceptable limits defined in the model's configuration file.
TypeError: object.__init__() takes exactly one argument (the instance to initialize)
This error indicates an incompatibility between the `ibm-watsonx-ai` library and Python 3.14, specifically due to changes in how `Enum.__init__` is handled in newer CPython versions.
fixUse a compatible Python version (e.g., Python 3.10, 3.11, or 3.12) for your development environment until the `ibm-watsonx-ai` SDK is updated to support Python 3.14.
400: Bad request - The request or response is invalid
The API request sent to watsonx.ai contains invalid input arguments, malformed data, or parameters that do not adhere to the service's API specifications, often including exceeding token limits for models in RAG experiments.
fixCarefully review the request payload, headers, and parameters to ensure they conform to the specific watsonx.ai API documentation. For RAG experiments, check if the input token count exceeds the model's limits and adjust document chunking or model selection.
Upgrade
Version history
1.7.1latest on PyPI · released Aug 26, 2026
Audit
Dependencies
No dependency data recorded yet.