{"id":1548,"library":"maturin","title":"Maturin","description":"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.","status":"active","version":"1.12.6","language":"en","source_language":"en","source_url":"https://github.com/pyo3/maturin","tags":["build tool","rust","pyo3","packaging","wheel","sdist","cffi","uniffi"],"install":[{"cmd":"pip install maturin","lang":"bash","label":"Install Maturin"}],"dependencies":[],"imports":[{"note":"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.","symbol":"maturin CLI","correct":"maturin <command>"}],"quickstart":{"code":"# Create a new maturin project (Python module named 'my_rust_package' with Rust code)\nmaturin new --binding pyo3 my_rust_package\n\n# Change into the new project directory\ncd my_rust_package\n\n# Build and install the package in editable mode for development\n# This makes the Rust extension available to your Python interpreter\nmaturin develop\n\n# You can now import your Rust module in Python:\n# python -c \"import my_rust_package; print(my_rust_package.sum_as_string(1, 2))\"","lang":"bash","description":"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."},"warnings":[{"fix":"Replace `maturin upload` with `twine upload dist/*` after building your wheels and sdists. Ensure `twine` is installed (`pip install twine`).","message":"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.","severity":"deprecated","affected_versions":">=1.11.2"},{"fix":"Install the Rust toolchain by following instructions on https://rustup.rs/ (recommended method using `rustup`).","message":"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.","severity":"gotcha","affected_versions":"All versions"},{"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.","message":"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.","severity":"gotcha","affected_versions":"All versions"},{"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.","message":"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.","severity":"gotcha","affected_versions":"<1.12.4 (platform tag detection for Android); <1.12.5 (debug info files)"}],"env_vars":null,"last_verified":"2026-04-09T00:00:00.000Z","next_check":"2026-07-08T00:00:00.000Z"}