Description

# Maturin _formerly pyo3-pack_ [](https://maturin.rs) [](https://crates.io/crates/maturin) [](https://pypi.org/project/maturin) [](https://discord.gg/33kcChzH7f) Build and publish crates with [pyo3, cffi and uniffi bindings](https://maturin.rs/bindings) as well as rust binaries as python packages with minimal configuration. It supports building wheels for python 3.8+ on Windows, Linux, macOS and FreeBSD, can upload them to [pypi](https://pypi.org/) and has basic PyPy and GraalPy support. Check out the [User Guide](https://maturin.rs/)! ## Usage You can either download binaries from the [latest release](https://github.com/PyO3/maturin/releases/latest) or install it with [pipx](https://pypa.github.io/pipx/) or [uv](https://github.com/astral-sh/uv): ```shell # pipx pipx install maturin # uv uv tool install maturin ``` > [!NOTE] > > `pip install maturin` should also work if you don't want to use pipx. There are three main commands: - `maturin new` creates a new cargo project with maturin configured. - `maturin build` builds the wheels and stores them in a folder (`target/wheels` by default), but doesn't upload them. It's recommended to publish packages with [uv](https://github.com/astral-sh/uv) using `uv publish`. - `maturin develop` builds the crate and installs it as a python module directly in the current virtualenv. Note that while `maturin develop` is faster, it doesn't support all the feature that running `pip install` after `maturin build` supports. maturin doesn't need extra configuration files and doesn't clash with an existing setuptools-rust configuration. You can even integrate it with testing tools such as [tox](https://tox.readthedocs.io/en/latest/). There are examples for the different bindings in the `test-crates` folder. The name of the package will be the name of the cargo project, i.e. the name field in the `[package]` section of `Cargo.toml`. The name of the module, which you are using when importing, will be the `name` value in the `[lib]` section (which defaults to the name of the package). For binaries, it's simply the name of the binary generated by cargo. When using `maturin build` and `maturin develop` commands, you can compile a performance-optimized program by adding the `-r` or `--release` flag. ## Python packaging basics Python packages come in two formats: A built form called wheel and source distributions (sdist), both of which are archives. A wheel can be compatible with any python version, interpreter (cpython and pypy, mainly), operating system and hardware architecture (for pure python wheels), can be limited to a specific platform and architecture (e.g. when using ctypes or cffi) or to a specific python interpreter and version on a specific architecture and operating system (e.g. with pyo3). When using `pip install` on a package, pip tries to find a matching wheel and install that. If it doesn't find one, it downloads the source distribution and builds a wheel for the current platform, which requires the right compilers to be installed. Installing a wheel is much faster than installing a source distribution as building wheels is generally slow. When you publish a package to be installable with `pip install`, you upload it to [pypi](https://pypi.org/), the official package repository. For testing, you can use [test pypi](https://test.pypi.org/) instead, which you can use with `pip install --index-url https://test.pypi.org/simple/`. Note that for [publishing for linux](#manylinux-and-auditwheel), you need to use the manylinux docker container or zig, while for publishing from your repository you can use the [PyO3/maturin-action](https://github.com/PyO3/maturin-action) github action. ## Mixed rust/python projects To create a mixed rust/python project, create a folder with your module name (i.e. `lib.name` in Cargo.toml) next to your Cargo.toml and add your python sources there: ``` my-project ├── Cargo.toml ├── my_project │   ├── __init__.py │   └── bar.py ├── pyproject.toml ├── README.md └── src    └── lib.rs ``` You can specify a different python source directory in `pyproject.toml` by setting `tool.maturin.python-source`, for example **pyproject.toml** ```toml [tool.maturin] python-source = "python" module-name = "my_project._lib_name" ``` then the project structure would look like this: ``` my-project ├── Cargo.toml ├── python │ └── my_project │ ├── __init__.py │ └── bar.py ├── pyproject.toml ├── README.md └── src    └── lib.rs ``` > [!NOTE] > > This structure is recommended to avoid [a common `ImportError` pitfall](https://github.com/PyO3/maturin/issues/490) matur