Install & Compatibility
Where this runs
tested against v1.11.7 · 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
433MB installed
● package 433MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
MistralTokenizer
✓ from mistral_common.tokens.tokenizers.mistral import MistralTokenizer
ChatCompletionRequest
✓ from mistral_common.protocol.instruct.request import ChatCompletionRequest
UserMessage
✓ from mistral_common.protocol.instruct.messages import UserMessage
Tool
✓ from mistral_common.protocol.instruct.tool_calls import Tool
Function
✓ from mistral_common.protocol.instruct.tool_calls import Function
MistralCommonBackend
✓ from mistral_common.tokens.tokenizers.mistral import MistralCommonBackend
✗ from transformers.models.mistral.tokenization_mistral_common import MistralCommonBackend
Directly importing internal modules like `MistralCommonBackend` from `transformers` or other libraries is discouraged as internal paths are unstable and can break. Rely on the `AutoTokenizer` or the official `mistral-common` import paths for stability.
This quickstart demonstrates how to tokenize a simple chat completion request using `mistral-common`. It involves defining user messages, creating a `ChatCompletionRequest`, and then encoding it into token IDs using a `MistralTokenizer`. For a real scenario, ensure the tokenizer model is correctly loaded, typically from a model name or a local file. The example includes a fallback for demonstration if a live tokenizer cannot be loaded.
from mistral_common.protocol.instruct.messages import UserMessage
from mistral_common.protocol.instruct.request import ChatCompletionRequest
from mistral_common.tokens.tokenizers.mistral import MistralTokenizer
import os
# NOTE: For actual inference, you would typically load a model tokenizer
# from a path or Hugging Face Hub. This example uses a placeholder.
# A real model_name would be 'mistral-large-latest' or 'open-mixtral-8x22b'
# For local development or specific tokenizer versions, a path can be used.
# For the purpose of a quickstart demonstration without an actual model download,
# we'll simulate the tokenizer loading or use a common one if available without heavy downloads.
# In a real scenario, you might do:
# tokenizer = MistralTokenizer.from_model("open-mixtral-8x22b")
# Or, if you have a local tokenizer:
# tokenizer = MistralTokenizer.from_file("path/to/tokenizer.model")
# For this quickstart, we will attempt to load a tokenizer that is generally available
# or illustrate the process. Assuming a tokenizer object can be instantiated for tokenization.
# In a production environment, ensure the tokenizer model is correctly loaded.
try:
# Attempt to load a common tokenizer for demonstration.
# 'open-mixtral-8x22b' is often used in examples.
tokenizer = MistralTokenizer.from_model("open-mixtral-8x22b")
except Exception as e:
print(f"Could not load tokenizer directly (e.g., model not found or network issue): {e}")
print("Please ensure you have the tokenizer model available or use a local path if preferred.")
print("For this quickstart, we will use a dummy tokenizer for demonstration purposes only.")
# Fallback to a dummy tokenizer if real one fails for demonstration
class DummyTokenizer:
def encode_chat_completion(self, request):
print("Using dummy tokenizer. No actual tokenization performed.")
return [1, 2, 3, 4, 5] # Dummy token IDs
tokenizer = DummyTokenizer()
messages = [
UserMessage(content="What is the capital of France?")
]
chat_completion_request = ChatCompletionRequest(messages=messages)
# Tokenize the chat completion request
token_ids = tokenizer.encode_chat_completion(chat_completion_request)
print(f"Original messages: {messages}")
print(f"Token IDs: {token_ids}")
Debug
Known issues
breakingApplications relying on strict parsing of streamed chunks may break due to a security-related change that added a new 'p' parameter to chunks. Update `mistral-common` to version 1.8.4 or higher to mitigate this.fixUpgrade to mistral-common >= 1.8.4.
affects: <1.8.4
gotchaDirectly importing internal modules (e.g., `MistralCommonBackend`) from `mistral-common` or other related libraries (like `transformers`) is generally discouraged. Internal file structures in fast-paced open-source libraries can change frequently, making your codebase brittle to minor updates. It is safer to rely on public APIs like `AutoTokenizer` when integrating with libraries such as Hugging Face Transformers.fixUse public API endpoints and classes as documented. Avoid deep imports from internal submodules unless explicitly instructed by official documentation.
affects: All versions
gotchaTokenizer versions are closely tied to Mistral model versions. Using an older `mistral-common` version with newer models or vice-versa might lead to incorrect tokenization or unexpected behavior. Verify compatibility between your `mistral-common` version and the Mistral model you intend to use.fixAlways check the official Mistral AI documentation or the `mistral-common` GitHub repository for recommended `mistral-common` versions compatible with specific Mistral models. Upgrade `mistral-common` when using new model releases.
affects: All versions
deprecatedThe `sentencepiece` tokenizer is now optional, as Mistral AI primarily releases `Tekken` tokenizers for recent models. While `sentencepiece` support is still available via an optional dependency, new projects might benefit from focusing on `Tekken`-based tokenization if working with the latest models.fixFor new models, consider using `Tekken` tokenizers. If you require `sentencepiece`, ensure you install `mistral-common[sentencepiece]`.
affects: >=1.3.1 (when Tekkenizer support was added)
gotchaWhen using `mistral-common`'s tokenizer via a Hugging Face `PreTrainedTokenizerBase` compatible interface, be aware of key behavioral differences. Special tokens are not encoded directly, and pairs of sequences are not supported. This can lead to unexpected results if relying on standard Hugging Face `PreTrainedTokenizer` behavior.fixRefer to the `mistral-common` documentation for specific behavior of its tokenizer, especially concerning special tokens and sequence handling, when used with Hugging Face interfaces.
affects: All versions
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'mistral_common'
The `mistral-common` package is not installed in your Python environment or the environment is not correctly activated.
fixEnsure you have installed the library using pip: `pip install mistral-common`. If you need additional features like image or audio tokenizers, install with extras, e.g., `pip install "mistral-common[image]"` or `pip install "mistral-common[all]"`.
AttributeError: 'MistralCommonTokenizer' object has no attribute 'all_special_tokens'
This usually occurs when integrating `mistral-common`'s tokenizer with other libraries (like `transformers` or `vLLM`) that expect a specific set of attributes or methods which might be missing or named differently in the current `mistral-common` tokenizer version, or due to version incompatibilities between the libraries.
fixEnsure `mistral-common` and any integrating libraries (e.g., `transformers`, `vLLM`) are updated to compatible versions. You might need to check the documentation or GitHub issues of the integrating library for specific version requirements with `mistral-common`. If using `vLLM`, ensure it is updated to a version that supports the `MistralCommonTokenizer`'s interface.
ValueError: Decoding `tokens` that contain special tokens ([X]) is not allowed. Either make sure `tokens` do not include any special tokens or, if you want to decode `tokens` that includes special tokens, change the tokenizer's special token policy to IGNORE or KEEP.
This error indicates that you are attempting to decode a sequence of tokens that includes special tokens without explicitly setting a policy for how these special tokens should be handled by the tokenizer.
fixWhen decoding, set the `special_token_policy` of your `MistralTokenizer` instance to `SpecialTokenPolicy.IGNORE` (to remove special tokens) or `SpecialTokenPolicy.KEEP` (to retain them as strings in the output).
```python
from mistral_common.tokens.tokenizers.mistral import MistralTokenizer
from mistral_common.tokens.tokenizers.tekken import SpecialTokenPolicy # or SentencePieceTokenizer for older models
# Assuming tokenizer is already loaded
# tokenizer = MistralTokenizer.from_model("model-name")
# To ignore special tokens
tokenizer.special_token_policy = SpecialTokenPolicy.IGNORE
decoded_string = tokenizer.decode(tokens_with_special_tokens)
# To keep special tokens
tokenizer.special_token_policy = SpecialTokenPolicy.KEEP
decoded_string = tokenizer.decode(tokens_with_special_tokens)
``` TypeError: ForwardRef._evaluate() missing 1 required keyword-only argument: 'recursive_guard' (or similar Pydantic version conflict messages)
This error, often manifesting as a `TypeError` or a dependency resolution failure during installation, typically arises from a version conflict with the `pydantic` library. `mistral-common` relies on `pydantic`, and if another library in your environment requires a different, incompatible version of `pydantic`, it can lead to runtime errors or installation issues.
fixEnsure that your `pydantic` installation is compatible with `mistral-common`. The `mistral-common` library specifies its `pydantic` requirements. Try to upgrade `mistral-common` to its latest version (`pip install --upgrade mistral-common`) or explicitly install a `pydantic` version that satisfies all your project's dependencies. You may need to create a new virtual environment to resolve conflicting dependencies.
ValueError: Unknown version: vXX in /path/to/tekken.json. Make sure to use a valid version string: ['v1', 'v2', 'v3', 'v7'] (example versions)
This error occurs when the `mistral-common` library attempts to load a tokenizer model (e.g., `tekken.json`) that has a version string not recognized by the installed `mistral-common` version. This typically means you are trying to use a newer model with an older `mistral-common` library, or vice-versa.
fixUpdate your `mistral-common` library to the latest version (`pip install --upgrade mistral-common`). This ensures compatibility with the tokenizer versions used by newer Mistral AI models. If you are working with an older model, you might need to use a `mistral-common` version that explicitly supports it.
Upgrade
Version history
1.11.7latest on PyPI · released Jul 23, 2026
Audit
Dependencies
pydanticrequiredCore library for data validation and settings management, foundational to mistral-common's data structures.
jsonschemarequiredRequired for schema validation.
numpyrequiredA fundamental package for scientific computing with Python.
pillowrequiredRequired for image processing utilities.
pydantic-extra-typesrequiredProvides additional Pydantic types.
requestsrequiredUsed for making HTTP requests, e.g., downloading tokenizers.
tiktokenrequiredA fast BPE tokenizer.
typing-extensionsrequiredBackports of new type hints in older Python versions.
uvlooprequiredA fast, drop-in replacement for the default asyncio event loop.
huggingface-hubrequiredOptional: to download tokenizers from the Hugging Face Hub.
sentencepiecerequiredOptional: to allow the use of SentencePiece tokenizers (now less common for new models).
fastapirequiredOptional: for the experimental REST API server.