Maturin — Build and Publish Rust-Python Packages

Introduction

Maturin bridges Rust and Python by compiling Rust crates into Python extension modules and packaging them as standard wheels. It supports PyO3 for native Rust-Python bindings, cffi for C-level interop, and uniffi for cross-language IDL. One command compiles, packages, and optionally publishes to PyPI.

What Maturin Does

• Compiles Rust code into Python-importable shared libraries
• Builds standards-compliant Python wheels with correct metadata
• Supports PyO3, rust-cpython, cffi, and uniffi binding modes
• Cross-compiles wheels for multiple platforms and Python versions
• Publishes directly to PyPI or a private index with maturin publish

Architecture Overview

Maturin reads your Cargo.toml for crate metadata and a pyproject.toml for Python packaging config. It invokes cargo build with the appropriate cdylib target, renames the output to match Python's naming convention, packs it with a dist-info directory into a wheel file, and writes PEP 517-compliant metadata. For cross-compilation, it leverages Rust's target triple system and zig as a linker when needed.

Setup & Configuration

• Install with pip install maturin or pipx install maturin
• Initialize a project with maturin init --bindings pyo3
• Configure in pyproject.toml under [tool.maturin] for Python-specific settings
• Use maturin develop during development to install directly into the active virtualenv
• Set compatibility in pyproject.toml for manylinux tag selection

Key Features

• Single command from Rust source to published PyPI package
• Automatic manylinux and musllinux compatibility tag detection
• Mixed Rust/Python projects with a python/ source directory alongside Rust
• Integration with cibuildwheel for CI matrix builds across platforms
• Supports PEP 621 metadata in pyproject.toml

Comparison with Similar Tools

• setuptools-rust — setuptools extension for Rust; maturin is standalone and faster to configure
• PyO3 — the bindings library itself; maturin handles the build and packaging layer on top
• cffi — C-level FFI; maturin can generate cffi bindings from Rust as an alternative to PyO3
• pybind11 — C++ to Python bindings; maturin focuses exclusively on the Rust ecosystem

FAQ

Q: Can I use maturin without PyO3? A: Yes. Maturin supports cffi and uniffi bindings, or you can build a pure cdylib and write the Python wrapper yourself.

Q: How do I cross-compile wheels for Linux on macOS? A: Use maturin build --target x86_64-unknown-linux-gnu --zig to cross-compile using zig as the C linker.

Q: Does maturin support Python type stubs? A: Yes. Place .pyi files in your Python source directory and maturin includes them in the wheel.

Q: Can I build wheels for multiple Python versions? A: Yes. Use maturin build --interpreter python3.10 python3.11 python3.12 to build separate wheels for each version.

Sources

• https://github.com/PyO3/maturin
• https://www.maturin.rs/