PyO3 setup Guide: Maturin

What is maturin?

• maturin is a specialized tool for building and publishing Rust crates as Python extension modules.
• It wraps around Cargo (Rust’s build system) and handles building, packaging, and publishing wheels to PyPI.
• Supports PyO3 and rust-cpython projects seamlessly.
• Simplifies Python packaging (wheels) for Rust extensions.

---

Step 1: Install prerequisites

• Rust toolchain: If not installed, get it here: https://rustup.rs

curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh

• Python 3.6+ installed and accessible in your PATH.
• maturin: Install via pip

pip install maturin

---

Step 2: Create new Rust library project

cargo new --lib my_pyo3_project cd my_pyo3_project

• This makes a Rust library project with the directory and default files.

---

Step 3: Configure Cargo.toml

Edit Cargo.toml to add PyO3 dependency and crate type:

[package]
name = "my_pyo3_project"
version = "0.1.0"
edition = "2021"

[lib]
crate-type = ["cdylib"]  # Compile to dynamic library for Python extension

[dependencies]
pyo3 = { version = "0.18", features = ["extension-module"] }

• cdylib is necessary to create a shared library loadable by Python.
• The extension-module feature enables integration with Python interpreter.

---

Step 4: Write Rust code exposing Python interface

Edit

src/lib.rs:

use pyo3::prelude::*;

// Annotate functions to expose them to Python
#[pyfunction]
fn double(x: usize) -> usize {
    x * 2
}

// Create Python module and add functions
#[pymodule]
fn my_pyo3_project(py: Python, m: &PyModule) -> PyResult<()> {
    m.add_function(wrap_pyfunction!(double, m)?)?;
    Ok(())
}

• #[pyfunction] marks Rust functions exposed to Python.
• #[pymodule] initializes the Python module with the same name as the Rust crate.

---

Step 5: Build & develop locally

Run:

maturin develop

• This command compiles Rust code, builds the Python extension, and installs it into your active Python environment.
• You can now import your module from Python for testing:

python

 

import my_pyo3_project
print(my_pyo3_project.double(21)) # prints 42

---

Step 6: Build distributable wheels

To create platform-specific wheels for distribution or upload to PyPI:

maturin build

 

• Builds .whl files inside target/wheels/.
• You can distribute these wheels or upload to PyPI.

---

Step 7: Publish to PyPI (optional)

If you want to publish your package:

maturin publish

• This uploads your wheels to PyPI.
• You need to have PyPI credentials configured (via .pypirc or environment variables).

---

Optional: Use pyproject.toml to configure build system

You can add this file to enable PEP 517 builds:

[build-system]
requires = ["maturin>=0.12"]
build-backend = "maturin"

[project]
name = "my_pyo3_project"
version = "0.1.0"
authors = ["Your Name <you@example.com>"]
description = "A simple Rust-Python example with PyO3"
readme = "README.md"
license = "MIT"
requires-python = ">=3.6"
keywords = ["rust", "pyo3", "python"]
classifiers = [
  "Programming Language :: Python :: 3",
  "Programming Language :: Rust",
]

• This allows building your package via pip directly, e.g.:
   

pip install .