Skip to main content

PyO3 Setup Guide: Install Rust and Maturin

A working PyO3 environment requires Rust, Python, and Maturin all in sync. This article provides a step-by-step checklist for macOS, Windows, and Linux. By the end, you will have a verified, production-ready setup that compiles extensions without warnings or missing dependencies.

The core stack is three components: Rust (the compiler and standard library), Python (3.7 or later), and Maturin (the Python package that glues them together). Each must be compatible with your OS and each other. Misconfiguration is the #1 cause of build failures among newcomers; this guide eliminates guesswork.

System Requirements​

PyO3 extensions require:

  • Python 3.7+ (3.10+ recommended for 2026 development)
  • Rust 1.56+ (1.70+ recommended)
  • Maturin 0.15.0+ (latest stable)
  • C/C++ compiler (for linking): MSVC on Windows, Clang on macOS, GCC on Linux
  • Git (for managing Rust dependencies)

Step 1: Install Rust via Rustup​

Rustup is the official Rust version manager. It handles compiler updates, target management, and toolchain switching automatically.

On macOS and Linux:

curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
source $HOME/.cargo/env

On Windows:

Download the installer from rustup.rs and run it. Choose the default settings (MSVC toolchain, which is pre-installed on modern Windows 10/11). Windows will prompt you to install the C++ Build Tools if missing; accept the prompt.

Verify the installation:

rustc --version
cargo --version

You should see output like rustc 1.75.0 (2024-01-01) and cargo 1.75.0. If you see command not found, add ~/.cargo/bin to your PATH (macOS/Linux) or restart your terminal (Windows).

Step 2: Verify Python and Create a Virtual Environment​

PyO3 binds to the Python interpreter you run it under. It is critical that your extension is compiled against the same Python version you will use in production.

Check your Python version:

python --version
python3 --version

If you have multiple Python versions, note the full path:

which python3  # macOS/Linux
where python   # Windows

Create a virtual environment (strongly recommended; never install into the system Python):

python -m venv pyo3_env
source pyo3_env/bin/activate  # macOS/Linux
# or
pyo3_env\Scripts\activate.bat  # Windows Command Prompt
# or
pyo3_env\Scripts\Activate.ps1  # Windows PowerShell (may require execution policy change)

Activate the environment before each session. You will see (pyo3_env) in your terminal prompt.

Step 3: Install Maturin and Development Tools​

Maturin is the modern Python–Rust build tool maintained by the PyO3 project. It handles compilation, linking, and wheel creation automatically.

In your activated virtual environment:

pip install --upgrade pip setuptools wheel
pip install maturin

Verify Maturin:

maturin --version

Output should be maturin X.Y.Z (e.g., maturin 0.15.2). If you see command not found, re-run the pip install command and check that the virtual environment is activated.

Step 4: Install Optional Build Dependencies​

For most projects, Maturin handles compilation transparently. However, you may need to install additional tools for specific scenarios:

On macOS:

If building for both Intel and ARM64 (Apple Silicon), install the cross-compilation toolchain:

rustup target add aarch64-apple-darwin

On Linux:

Ensure development headers are installed:

# Debian/Ubuntu
sudo apt-get install python3-dev build-essential

# Fedora/RHEL
sudo dnf install python3-devel gcc gcc-c++ make

On Windows:

If the Rust installer did not auto-install C++ Build Tools, download them from Microsoft Visual Studio Build Tools. Choose the "Desktop development with C++" workload.

Step 5: Create Your First Maturin Project and Verify​

Once all prerequisites are installed, scaffold a test project:

maturin new test_pyo3 --bindings pyo3
cd test_pyo3

The directory structure should look like this:

test_pyo3/
├── Cargo.toml
├── pyproject.toml
├── README.md
└── src/
    └── lib.rs

Build the project:

maturin develop

This compiles the test extension and installs it. Output should end with Installed test_pyo3. If you see linker errors or missing dependencies, review the error message and return to the relevant step above.

Run a quick test:

python -c "from test_pyo3 import sum_as_string; print(sum_as_string([1, 2, 3]))"

Expected output: 6. If this runs without error, your setup is complete and verified.

Troubleshooting Common Setup Issues​

IssueSolution
rustc: command not foundRustup did not add ~/.cargo/bin to PATH. Run source ~/.cargo/env (macOS/Linux) or restart your terminal (Windows).
ModuleNotFoundError: No module named 'maturin'Virtual environment not activated, or pip install failed. Run which maturin (macOS/Linux) or where maturin (Windows) to verify the path; if it is not in your venv, reinstall.
error: linker 'cc' not found (Linux)C compiler not installed. Run sudo apt-get install build-essential (Debian) or sudo dnf install gcc (Fedora).
error: linker 'cl.exe' not found (Windows)MSVC toolchain not installed. Run the Visual Studio Build Tools installer and select "Desktop development with C++".
error: Python headers not foundPython development headers not installed. On Linux, run sudo apt-get install python3-dev. On macOS, they are bundled with Python; if missing, reinstall Python via Homebrew: brew install [email protected].

Verify Your Setup Checklist​

  • rustc --version prints a version number (1.56+)
  • cargo --version prints a version number
  • python --version prints a version (3.7+)
  • Virtual environment created and activated (prompt shows (pyo3_env) or similar)
  • pip install maturin completed without errors
  • maturin --version prints a version (0.15.0+)
  • maturin develop builds a test project without linker errors
  • Test project can be imported and called from Python

Key Takeaways​

  • Rust, Python, and Maturin must be compatible; use Rustup to manage Rust versions.
  • Always use a virtual environment to isolate PyO3 projects from system Python.
  • Maturin automates the build process; verify with a test project before starting real work.
  • Missing C++ build tools or Python headers are the most common setup failures; address them early.
  • On macOS and Linux, ensure PATH includes ~/.cargo/bin; on Windows, verify MSVC installation.

Frequently Asked Questions​

Can I use PyO3 with Python 3.6 or older?​

PyO3 officially supports Python 3.7 and later. Python 3.6 reached end-of-life in December 2021. Always upgrade to a supported version for security and feature compatibility.

Do I need to manually manage Rust toolchains?​

Rustup manages toolchains for you. Most projects use the stable channel (the default). If a project specifies a nightly feature, add it with rustup toolchain install nightly and add a rust-toolchain.toml to your project root. For PyO3 extensions, stable is sufficient.

What is the difference between maturin develop and maturin build?​

maturin develop compiles and installs the wheel as an editable package in your virtual environment (suitable for local development). maturin build outputs a wheel file in a target/wheels/ directory (suitable for distribution). Use develop during development; use build before publishing.

How do I know if my C compiler is correctly configured?​

Run rustc --print sysroot and check the output. On Windows, the output should include a path to the MSVC toolchain (e.g., C:\Users\...\rustup\toolchains\stable-x86_64-pc-windows-msvc). If the path is missing or points to an invalid location, reinstall Rust with rustup self uninstall and then curl ... | sh.

Further Reading​