Maturin

Common errors

• maturin failed Caused by: Cargo metadata failed.

  cause Maturin relies on `cargo metadata` to gather information about your Rust project, and this error indicates that `cargo metadata` failed, often due to issues with the Rust toolchain, a malformed `Cargo.toml`, or the Rust project itself not compiling with `cargo build`.
  fix Ensure Rust and Cargo are correctly installed and in your system's PATH. Run `cargo build` in your Rust project directory to diagnose and fix Rust-specific compilation errors. Verify your `Cargo.toml` file for syntax errors or incorrect paths, especially for local dependencies. Update `cargo` if necessary using `rustup update`.

• FileNotFoundError: [Errno 2] No such file or directory: 'maturin'

  cause This error typically means that the `maturin` executable itself cannot be found in the system's PATH, or that the `python` directory specified in `pyproject.toml` or implicitly expected by `maturin` (for Python source files) does not exist or is misconfigured. In some specific environments (like FreeBSD ports with non-default Python versions), `maturin-<ver>` might be installed instead of `maturin`.
  fix Ensure `maturin` is installed in the active Python environment (`pip install maturin`) and that its installation directory is in your system's PATH. If using a specific Python version, ensure `maturin` is installed for that version (e.g., `python3.x -m pip install maturin`). If you have a `python-source = "python"` entry in your `pyproject.toml`, ensure there is a `python/` directory at the root of your project containing your Python source files. Adjust `python-source` if your Python code is located elsewhere or remove it if not needed.

• maturin failed Caused by: Failed to build a native library through cargo Caused by: Cargo build finished with "exit status: 101": `env -u CARGO PYO3_BUILD_EXTENSION_MODULE="1" PYO3_ENVIRONMENT_SIGNATURE="cpython-3.14-64bit" PYO3_PYTHON="/home/user/.` (mentioning an unreleased or very new Python version)

  cause Maturin and PyO3 might not yet fully support very new or pre-release Python versions (e.g., Python 3.13, 3.14) due to ABI changes or build system incompatibilities. This forces a source build which then fails because the necessary bindings or toolchain configurations are not stable for that specific Python version.
  fix Use a stable and officially supported Python version (e.g., 3.8-3.12 for current `maturin`/`pyo3` releases). If building with a newer Python version is strictly necessary and you understand the risks, try setting the environment variable `PYO3_USE_ABI3_FORWARD_COMPATIBILITY=1`, though this might lead to other compatibility issues. Consider downgrading your Python environment if possible.

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.
• gotcha Shell commands like `maturin new` cannot be directly executed by the Python interpreter. Placing them directly into a Python script will result in a `SyntaxError`.
  Fix: To run `maturin` or other shell commands from a Python script, use Python's `subprocess` module (e.g., `subprocess.run(['maturin', 'new', '--binding', 'pyo3', 'my_rust_package'], check=True)`).
• gotcha The script attempts to execute a `maturin` command (e.g., `maturin new`) as Python code, resulting in a `SyntaxError: invalid syntax`. `maturin` commands are shell commands and should be run in a shell environment or via Python's `subprocess` module.
  Fix: Ensure `maturin` commands are executed in a shell environment, or use `subprocess.run(['maturin', 'new', '--binding', 'pyo3', 'my_rust_package'], check=True)` in Python scripts to execute them correctly.

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))"