Install the Workflows SDK

Technical prerequisites

You need four things in place before writing your first line of workflow code. First, you need Python 3.12 or higher because workflows rely on modern async features introduced in this version. Python 3.11 will fail at import time, not runtime, which at least makes the error immediate. Second, you need uv, the package manager Mistral recommends for Python projects. It handles both virtual environments and dependencies. Finally, you need a Mistral AI account. Create one at console.mistral.ai if you haven’t already, and generate an API key in the API Keys section of the console.

Check your Python version

Start with the most common blocker: the interpreter version.

python --version
# Must show Python 3.12.x or higher

If your version is lower than 3.12, update Python before continuing. On Ubuntu/Debian:

sudo apt update
sudo apt install python3.12 python3.12-venv

On macOS with Homebrew:

brew install [email protected]

Install uv

If you don’t have uv yet, install it. The command differs by system:

# Linux / macOS
curl -LsSf https://astral.sh/uv/install.sh | sh

# Windows (PowerShell)
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

Then verify the binary is in your PATH. If the following command returns “not found,” open a new terminal. The installer modifies your shell profile:

uv --version

Create a project

Create a new Python project with uv:

mkdir mon-workflow-mistral
cd mon-workflow-mistral
uv init

This creates a pyproject.toml file and a standard project structure. The pyproject.toml file lists your dependencies and lets a colleague recreate the exact same environment.

You have two installation options, and the choice matters. If you only need the workflow engine—because your activities call internal APIs, a database, or third-party services—the basic version is enough:

uv add mistralai-workflows

If you want to use durable agents, tool calling, and multi-agent handoffs directly in your workflows, use the variant with extras:

uv add "mistralai-workflows[mistralai]"

The second option installs the Mistral AI SDK as a dependency and enables native integrations with Mistral models. If you’re unsure at the start of a project, the basic version is lighter. You can add the extra later without breaking anything.

Verify the installation

A successful import beats a long manual check:

uv run python -c "import mistralai.workflows; print('Workflows SDK installed successfully!')"

You should see:

Workflows SDK installed successfully!

If you get a ModuleNotFoundError, don’t reinstall immediately. First, check that you’re in the project folder where you ran uv add. The uv run command resolves the virtual environment from the current directory.

Configure your API key

The SDK authenticates via the MISTRAL_API_KEY environment variable. It reads this automatically; you don’t need to pass it as an argument. Set it in your terminal:

# Linux / macOS
export MISTRAL_API_KEY="votre_clé_api_ici"

# To make it permanent, add it to your ~/.bashrc or ~/.zshrc
echo export MISTRAL_API_KEY=votre_clé_api_ici >> ~/.bashrc

This method works for local development. For production projects, prefer a .env file loaded via python-dotenv or your deployment platform’s secrets manager. A key in a .bashrc file will eventually end up in a backup or a screen share.

Quick scaffolding (optional)

Mistral provides a CLI tool that generates a complete workflow project. This is useful for seeing the expected structure before writing your own:

uvx mistralai-workflows-cli setup

The command produces a sample workflow file, an activity file, a ready-to-start worker, and basic configuration. In seconds, you get a running project. You can then take it apart piece by piece to understand the role of each component before starting from scratch.

Recommended project structure

For a production workflow project, we recommend this structure:

mon-workflow-mistral/
├── pyproject.toml          # Dependencies (mistralai-workflows)
├── .env                    # API key (do not commit)
├── activities/
│   ├── __init__.py
│   ├── email.py            # Email-related activities
│   └── data_processing.py  # Data processing activities
├── workflows/
│   ├── __init__.py
│   └── pipeline.py         # Workflow definitions
└── worker.py               # Worker entry point

Separating activities from workflows makes maintenance and unit testing easier. An activity is a standard async function you can call directly in a test, while a workflow requires the engine to run. This separation takes five minutes at the start of a project and saves you a lot of time once you have more than ten activities.

Key takeaways

Python 3.12+ and uv are required for the Workflows SDK
Two installation modes: basic (mistralai-workflows) or with AI integration (mistralai-workflows[mistralai])
Configure the API key via the MISTRAL_API_KEY environment variable
The uvx mistralai-workflows-cli setup command generates a complete sample project
Separate your activities, workflows, and worker into distinct files for better maintainability