# Maturin — Build and Publish Rust-Python Packages

> A build tool for creating Python packages from Rust code using PyO3, rust-cpython, cffi, or uniffi bindings. Handles compilation, wheel building, and PyPI publishing in a single command.

## Install

Save in your project root:

# Maturin — Build and Publish Rust-Python Packages

## Quick Use
```bash
pip install maturin
mkdir my-rust-lib && cd my-rust-lib
maturin init --bindings pyo3
maturin develop    # build and install into current venv
maturin build      # build wheel for distribution
```

## 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/

---
Source: https://tokrepo.com/en/workflows/asset-57e0a645
Author: AI Open Source