Install & Compatibility
Where this runs
tested against v2.9.4 · 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 1.050s · 50MB
glibcpy 3.10–3.95 runs
installs and imports cleanly · install 5.8s · import 0.942s · 50MB
50MB installed
● package 50MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
Mistral
✓ from mistralai.client import Mistral
✗ from mistralai import Mistral
Starting with v2.x, the main client class was moved into the `client` submodule. Direct import from `mistralai` will result in an `AttributeError`.
This quickstart initializes the Mistral client and performs a simple chat completion request. It assumes the `MISTRAL_API_KEY` environment variable is set for authentication. The response content is then printed.
import os
from mistralai.client import Mistral
# Ensure MISTRAL_API_KEY environment variable is set
api_key = os.environ.get('MISTRAL_API_KEY', '')
if not api_key:
print("Error: MISTRAL_API_KEY environment variable not set.")
print("Please set it using: export MISTRAL_API_KEY='your_api_key_here'")
else:
try:
client = Mistral(api_key=api_key)
chat_response = client.chat.complete(
model="mistral-small-latest",
messages=[
{"role": "user", "content": "What is the capital of France?"}
]
)
print(chat_response.choices[0].message.content)
except Exception as e:
print(f"An error occurred: {e}")
Debug
Known issues
breakingThe import path for the `Mistral` client class changed significantly from v1.x to v2.x. Old code importing `from mistralai import Mistral` will fail.fixUpdate your imports to `from mistralai.client import Mistral`.
affects: 2.0.0 and later
breakingThe structure of response objects, specifically `response.choices[]`, changed in v2.x for methods like `mistral.chat.complete()`, `mistral.fim.complete()`, and `mistral.agents.complete()`.fixRefer to the official migration guide (e.g., `MIGRATION.md` on GitHub) to adapt your code to the new response payload structure. For chat completions, content is now often accessed via `response.choices[0].message.content`.
affects: 2.0.0 and later
gotchaAPI Key (`MISTRAL_API_KEY`) is crucial for authentication. Not setting it as an environment variable or passing it directly to the client will lead to authentication errors.fixSet `export MISTRAL_API_KEY='your_api_key_here'` in your environment or explicitly pass `api_key='your_api_key_here'` during client initialization.
affects: All versions
gotchaIncorrect data serialization when sending requests to the API can lead to 'Data Serialization Error'.fixEnsure that the data you send in API requests (e.g., messages, tool definitions) strictly adheres to the format specified in the Mistral AI API documentation.
affects: All versions
gotchaCommon API errors include 401 (Unauthorized), 413 (Payload Too Large/Context Window Overflow), and 429 (Rate Limit Exceeded).fixImplement robust error handling, including retries with exponential backoff for transient errors (429). For 413, review prompt length and model context window limits. Ensure API key is valid for 401 errors.
affects: All versions
deprecatedSeveral older models, such as `open-mistral-7b`, `mistral-tiny`, `mistral-medium-2312`, and certain dated model aliases, have been deprecated.fixUpdate to newer, recommended models for continued support and improved performance. Check the latest model availability via the API or official documentation.
affects: Refer to Mistral AI's official model documentation for specific deprecation dates.
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'mistralai'
The 'mistralai' library is not installed in your Python environment, or there's an issue with the installation path.
fixRun `pip install mistralai` to install the library. If the error persists for submodules (e.g., `mistralai.models.chat_completion`), ensure you have the latest version (`pip install --upgrade mistralai`) and check the official documentation for potential breaking changes in import paths between major versions (e.g., v1 to v2).
AuthenticationError: Invalid API key
The API key provided is missing, incorrect, expired, or does not have the necessary permissions to access the Mistral AI API.
fixEnsure your `MISTRAL_API_KEY` environment variable is correctly set with a valid API key obtained from your Mistral AI dashboard. Alternatively, pass the `api_key` directly to the `MistralClient` constructor: `client = MistralClient(api_key="YOUR_API_KEY")`.
APIError: Bad Request
The request sent to the Mistral AI API is malformed, contains invalid parameters (e.g., incorrect model name, wrong message roles, unsupported fields), or does not adhere to the API's specifications.
fixCarefully review your API request payload, specifically checking the model name, message structure (roles and content), and any other parameters, ensuring they align with the Mistral AI API documentation for the specific endpoint and model you are using.
RateLimitError: Rate limit exceeded
Your application has sent too many requests or consumed too many tokens within a short period, exceeding the rate limits imposed by the Mistral AI API for your account.
fixImplement robust error handling with exponential backoff and retry logic for API calls. Consider optimizing your usage patterns or contacting Mistral AI support to inquire about increasing your rate limits if higher throughput is consistently required.
AttributeError: 'ChatMessage' object has no attribute 'model_dump'
This error typically occurs due to a breaking change in the 'mistralai' library, particularly during major version upgrades (e.g., from v0.x to v1.x or v2.x), where certain object methods or attributes like `model_dump` have been renamed or removed.
fixConsult the official Mistral AI Python client migration guide for your specific version upgrade. For this particular error, try using `message.model_dump_json()` or `message.dict()` if your intent is to serialize the `ChatMessage` object, as method names often change between versions.
Upgrade
Version history
2.9.4latest on PyPI · released Aug 21, 2026
Audit
Dependencies
pythonrequiredMinimum required Python version for the SDK.
httpxrequiredUsed internally for making HTTP API calls.