Maturin

1.12.6 · active · verified Thu Apr 09

Maturin is a build tool designed to create and publish Python packages that incorporate Rust code via PyO3, cffi, or uniffi bindings, as well as standalone Rust binaries. It automates much of the complex build process for hybrid Python-Rust projects, including wheel and sdist generation. The current version is 1.12.6, and it sees frequent minor releases to address bugs and add features.

Warnings

deprecated The `maturin upload` command is deprecated and will be removed in Maturin 2.0. It is recommended to use `twine upload` instead for uploading packages to PyPI or other indexes.
Fix: Replace `maturin upload` with `twine upload dist/*` after building your wheels and sdists. Ensure `twine` is installed (`pip install twine`).
gotcha Maturin requires a working Rust toolchain (rustc and cargo) to be installed and available in your system's PATH. Without it, Maturin cannot compile your Rust code into Python extensions.
Fix: Install the Rust toolchain by following instructions on https://rustup.rs/ (recommended method using `rustup`).
gotcha Ensure your `pyo3` dependency version in `Cargo.toml` is compatible with the `maturin` version you are using, especially when targeting specific Python versions or using advanced `pyo3` features. Mismatches can lead to compilation failures or runtime errors.
Fix: Consult the `maturin` and `pyo3` documentation for recommended version pairings. Update `pyo3` in your `Cargo.toml` and potentially `maturin` itself if necessary. `maturin` will often provide helpful error messages for major incompatibilities.
gotcha When building for specific platforms or cross-compiling, platform tags can sometimes be misdetected, or target-specific libraries might not be correctly included. This can result in wheels that don't install or run on the intended target.
Fix: Always test your generated wheels on the target platforms. For complex scenarios, explicitly specify target platforms using `maturin build --target <TRIPLE>`. Ensure you are on the latest `maturin` version, as many platform-specific issues are actively addressed.

Install

pip install maturin Install Maturin

Imports

maturin CLI
```
maturin <command>
```
Maturin is primarily a command-line interface (CLI) tool and is not typically imported or used programmatically within Python scripts. Its functionality is accessed through the 'maturin' executable.

Quickstart

This quickstart demonstrates how to create a new PyO3-based Python project with Maturin, then build and install it in editable mode for development. The `maturin develop` command handles compiling the Rust code and making it available to your Python environment.

# Create a new maturin project (Python module named 'my_rust_package' with Rust code)
maturin new --binding pyo3 my_rust_package

# Change into the new project directory
cd my_rust_package

# Build and install the package in editable mode for development
# This makes the Rust extension available to your Python interpreter
maturin develop

# You can now import your Rust module in Python:
# python -c "import my_rust_package; print(my_rust_package.sum_as_string(1, 2))"

view raw JSON →