PyO3/maturin

This system is a CLI tool and Python build backend designed to compile Rust code into Python extension modules and wheels. It supports multiple binding technologies, including PyO3, CFFI, and UniFFI, enabling the creation of pure Rust libraries, mixed Rust-Python packages, and standalone binaries. The tool handles the full build lifecycle, including project scaffolding, dependency resolution, wheel auditing, and source distribution generation, while providing automated CI workflow creation and type stub generation.

31 changes.

This period established the project's foundational structure, including repository configuration, CI migration, and the introduction of a PEP 517 build backend. It focused heavily on expanding test coverage by adding numerous crates for PyO3, CFFI, and path dependency scenarios, while also implementing native Rust auditwheel support and modernizing project templates.

22 changes.

This period focused on significantly expanding test coverage by introducing numerous test crates for PyO3, UniFFI, and various project layouts, alongside snapshot tests for CLI help output. Concurrently, the Python interpreter discovery logic was refactored into a unified pipeline to better support free-threaded interpreters and cross-compilation scenarios.

24 changes.

This period focused on a major architectural overhaul, refactoring the build context, bridge detection, and binding generation into modular, trait-based systems to improve maintainability and support complex workspace structures. It introduced new capabilities such as the \generate-ci\ command for automated GitHub Actions workflows, \uv\ support in development, and automated Python type stub generation. Comprehensive test coverage was added to validate these changes, including specific fixtures for UniFFI multi-crate scenarios, PyO3 abi3t features, and deterministic source distribution building.

A new test crate for mixed Rust and Python projects has been added, providing a Python package that exposes CFFI bindings. The package includes a Line class that constructs geometric lines using Rust-backed Point structs and calculates their length, along with a check\_installed script to verify that the CFFI library functions (get\_origin, is\_in\_range) and the Line class work correctly.

_test-crates/cffi-mixed/cffi\mixed · high confidence

A new Python module \pyo3\_mixed\_workspace\_py\ has been added to expose the \get\_21\_lib\ function from the Rust workspace. Users can now call the \get\_21()\ function from Python, which returns the value produced by the underlying Rust implementation.

test-crates/pyo3-mixed-workspace/rust/python/pyo3-mixed-workspace-py · high confidence

The test crate now includes a Python package structure with a \double\ utility function that doubles an integer result from a provided callable, and exposes it alongside the existing \get\21\ function from the PyO3 extension module via the main package \\\init\\_.py\.

test-crates/pyo3-mixed-py-subdir/python · high confidence

Added a new \hello-world\ test crate containing two Rust binaries (\hello-world\ and \foo\), along with included and excluded examples and benchmarks, to support testing mixed Rust/Python project scenarios and binary distribution.

test-crates/hello-world · high confidence

The guide directory now uses mdBook to generate the Maturin User Guide, configured via a new book.toml that points to the source directory and GitHub repository. A custom tweak.css file has been added to style a sponsors section, allowing sponsor logos or names to be displayed in a responsive, centered layout within the generated documentation.

guide · high confidence

A new test crate \test-crates/pyo3-bin\ has been added to verify the PyO3 binary integration. It includes a Rust binary (\src/main.rs\) that attaches to the Python interpreter, executes a Python function (\sum\), and prints a success message, alongside a Python script (\check\_installed/check\_installed.py\) that ensures the binary runs correctly by handling platform-specific library paths on Windows, macOS, and Linux.

test-crates/pyo3-bin · high confidence

A new test crate named \pyo3-pure\ has been added to the \test-crates\ directory to validate the pure Rust project layout. This crate includes a Rust implementation exposing a \DummyClass\ and a module-level constant, accompanied by a corresponding \.pyi\ type stub file to support static type checking. The entry also provides a \tox.ini\ configuration for running tests across Python 3.6, 3.7, and 3.8, along with standard documentation and licensing files.

test-crates/pyo3-pure · high confidence

A new test crate has been added to validate the uniffi-pure-proc-macro library mode. It includes a Rust library exposing a simple addition function via uniffi, a Python test script to verify the binding works correctly, and the necessary configuration files (uniffi.toml and uniffi-bindgen.rs) to generate and test the Python bindings.

test-crates/uniffi-pure-proc-macro · high confidence

A new test crate named \uniffi-mixed\ has been added to validate the generation of Python bindings via uniffi. This includes a UDL interface defining a math namespace with an \add\ function, a Rust library implementation, and a build script to generate the scaffolding. The entry also includes Python test scripts (\check\_installed.py\ and \test\_uniffi\_mixed.py\) that verify the \add\ function works correctly in the generated Python module.

test-crates/uniffi-mixed, test-crates/uniffi-pure · high confidence

Added two new example projects, \cffi-mixed\ and \cffi-pure\, under \test-crates\ to demonstrate building Rust libraries with CFFI bindings using maturin. The \cffi-pure\ crate provides a standalone Rust library exposing C-compatible functions (such as \get\_origin\ and \is\_in\_range\) for Python consumption, while \cffi-mixed\ extends this with a Python wrapper class (\Line\) around the Rust \Point\ type. Both crates include Python test suites and tox configurations to validate the bindings across Python 3.6, 3.7, and 3.8.

test-crates/cffi-mixed, test-crates/cffi-pure · high confidence

A new test crate has been added to the Python workspace to serve as a basic integration point, containing a standard Rust entry point that prints a confirmation message.

test-crates/workspace/py · high confidence

A new test crate named pyo3-mixed-src has been added to demonstrate a mixed Python and PyO3 project using the modern 'src' layout. This includes the package structure under src/pyo3\_mixed\_src, a helper module for doubling values, and a verification script to ensure the installed package functions correctly. The crate also provides a tox configuration for running tests across Python 3.6 through 3.8 and a README explaining its purpose as a test fixture for maturin.

test-crates/pyo3-mixed-src · high confidence

Added two new scripts to the test-crates directory to streamline maintenance tasks. The \update\_readme.py\ script automatically synchronizes usage examples in documentation files (such as README.md and guide pages) with the current output of maturin commands, ensuring docs stay accurate without manual updates. The \cargo-update.sh\ script provides a convenient way to run \cargo update\ across all subdirectories containing a Cargo.lock file, simplifying dependency updates for the test crate suite.

test-crates · high confidence

Developers can now use a pre-configured VS Code devcontainer to build and test the project. The environment is based on the official Rust bullseye image and automatically installs Python development dependencies (including cffi, virtualenv, and pipx), the uniffi-bindgen tool, and cargo-deny. It also configures VS Code with the Ruff and Black formatters, enables format-on-save, and adds the wasm32-wasip1 Rust target alongside the nextest runner. SSH access is enabled via the devcontainer sshd feature.

.devcontainer · high confidence

The repository is initialized with essential configuration files including a pre-commit setup (ruff, mypy, codespell), a Dockerfile for building the CLI in manylinux/musl environments, a noxfile for automation, and a JSON schema for the pyproject.toml configuration. Documentation is structured with an mdBook guide, a git-cliff changelog generator, and an AGENTS.md file outlining project conventions and build instructions.

(repo-wide) · high confidence

Maturin now includes a Python-based PEP 517 build backend (in \maturin/\_\init\\.py\, \\\main\\_.py\, and \bootstrap.py\) that allows building wheels and source distributions directly via the Python interface. This enables running \python3 -m maturin\ and supports self-contained bootstrapping by automatically installing Rust via \puccinialin\ when \cargo\ is not found. The backend respects \config\_settings\ for arguments, defaults compatibility to 'off', and ensures correct interpreter paths using \sys.executable\.

maturin · high confidence

Added a new \generate-ci\ command that allows users to automatically generate GitHub Actions CI workflows. This feature introduces a \Provider\ enum (currently supporting GitHub) and a \Platform\ enum covering Linux (ManyLinux, Musllinux), Windows, macOS, Emscripten, and Android. The implementation includes logic to resolve default runners, target architectures, and Python architectures for each platform, and defines a \ResolvedCIConfig\ structure to merge CLI arguments with \pyproject.toml\ settings for pytest, Zig cross-compilation, and trusted publishing.

src/ci · high confidence

Users can now bootstrap new Rust/Python projects with \maturin new\ and \maturin init\, which generate a \pyproject.toml\-based layout (including optional \src\ layout), CI workflows, and templates for PyO3, CFFI, UniFFI, or binary bindings. The build system now supports Profile-Guided Optimization (PGO) via the \--pgo\ flag and \MATURIN\_PGO\ environment variable to improve runtime performance. Additionally, wheel ZIP compression is configurable via \--compression-method\ (Deflate, Stored, Bzip2, Zstandard) and \--compression-level\, allowing users to balance build speed and wheel size. A new \generate-json-schema\ command also provides a JSON schema for \pyproject.toml\ validation.

src · high confidence

The \maturin develop\ command now supports using \uv\ as the package installer instead of \pip\, activated via the new \--uv\ flag. This change introduces logic to detect \uv\ binaries (both standalone and as a Python module) and sets the \UV\_PYTHON\ environment variable when invoking \uv pip install\. Additionally, the tool now detects virtual environments created by \pixi\ (by checking for \conda-meta/pixi\_env\_prefix\) and handles them correctly, ensuring compatibility with pixi-managed development workflows.

src/develop · high confidence

The build context has been decomposed into three distinct sub-contexts—ProjectContext (static project metadata and layout), ArtifactContext (output configuration like stripping, compression, and PGO), and PythonContext (target environment and auditwheel settings)—to improve code organization and hygiene. A new BuildContextBuilder is now used to construct the context from BuildOptions, providing a cleaner, chainable API for configuration. This change also introduces the WheelRepairer trait and platform-specific repairers (ElfRepairer, MacOSRepairer, WindowsRepairer) to handle wheel repair logic more modularly.

_src/build\context · high confidence

The test crate now supports a Python-first project layout by introducing a Rust source file at src/lib.rs. This file defines a PyO3 module named pyo3\_mixed\_src that exposes a single function, get\_21, which returns the integer 21, enabling the test suite to validate the new directory structure.

test-crates/pyo3-mixed-src/rust · high confidence

The sdist generation logic has been corrected to properly handle transitive path dependencies within workspaces. Previously, non-path dependencies might have been incorrectly included or excluded; the change ensures that only relevant path-dependent crates are packaged, preventing build failures or missing artifacts when consuming the source distribution.

_test-crates/workspace\_with\_path\dep/python · medium confidence

The module writer now resolves include/exclude glob patterns relative to the project root first, falling back to the python-source directory when necessary, which ensures that a single pattern works consistently for both wheels and source distributions. It also switches source distribution archives from GNU tar headers to the PAX format to support longer paths and non-ASCII characters, and enforces deterministic timestamps and sorted file ordering to guarantee reproducible builds.

_src/module\writer · high confidence

The source distribution (sdist) generation logic has been refactored to correctly handle complex Rust workspace structures. It now supports parent-relative paths in pyproject.toml metadata (readme, license) by rewriting them to valid archive paths, and it properly manages parent workspaces by stripping non-workspace tables from the root Cargo.toml and inlining workspace-inherited fields when a dependency's workspace manifest falls outside the sdist root. Additionally, the sdist now only includes path dependencies that are actually used, reducing distribution size, and correctly resolves symlinks and cross-workspace path dependencies.

_src/source\distribution · high confidence

The \src/auditwheel\ module now provides a native Rust implementation for wheel auditing and repair, replacing the previous external tool dependency. This change introduces a new \AuditWheelMode\ enum that allows users to select between \Repair\ (the default), \Check\ (audit only), \Warn\ (report issues without failing), and \Skip\ (disable auditing). The module includes platform-specific repairers: \ElfRepairer\ for Linux (using \patchelf\ and \lddtree\), \MacOSRepairer\ for macOS (bundling dylibs and rewriting install names), and \WindowsRepairer\ for Windows (patching PE import tables). It also adds support for musllinux policies and cross-platform ad-hoc code signing for macOS binaries.

src/auditwheel · high confidence

The \generate-ci github\ command now produces updated GitHub Actions workflows that use \actions/checkout@v6\, \actions/setup-python@v6\, and \actions/upload-artifact@v6\. The generated release jobs include artifact attestation via \actions/attest@v4\ and trusted publishing via \uv publish\. The generator now supports configuration via \\[tool.maturin.generate-ci.github\]\ in \pyproject.toml\, allowing users to specify targets, runners, and options like \pytest\, \zig\, and \skip\_attestation\. It also supports building free-threaded wheels (Python 3.14t) for abi3 projects and includes Emscripten (wasm32) support.

src/ci/github · high confidence

The \src/target\ module has been refactored to introduce strict PyPI platform tag validation and comprehensive platform tag generation. A new \legacy\_py\ module mirrors PyPI's \legacy.py\ allow-lists and regex patterns to validate wheel filenames against PyPI's upload requirements, ensuring that only supported architectures (such as \armv6l\, \armv7l\, and \riscv64\) and OS combinations are accepted. The \platform\_tag\ module now generates correct tags for a wider range of targets, including iOS (device and simulator), Android, Cygwin, AIX, and Emscripten, while respecting deployment targets. Additionally, the \wheel\_tag\ module handles PEP 425 compressed tag sets, sorting them and expanding them into fully qualified tags for the final wheel filename.

src/target · high confidence

Generated projects now default to the Rust 2024 edition and PyO3 version 0.29.0, with Uniffi templates updated to version 0.28.0. The templates also include a .gitignore file covering common Python and Rust build artifacts, and the Python package initialization now conditionally re-exports \_\all\\_ if defined by the underlying Rust module.

src/templates · high confidence

The binding generation logic for PyO3, CFFI, UniFFI, and binary bindings has been migrated to a new \BindingGenerator\ trait. This change introduces a consistent interface for producing bindings, replacing the previous ad-hoc generation methods. Users benefit from a more robust and maintainable build process, particularly for binary wheels with external shared library dependencies (which now use a shim script to ensure correct runtime paths) and improved handling of WASI targets. The refactoring also enables better support for mixed PyO3 projects and ensures type stubs are correctly generated and placed within the module's package directory.

_src/binding\generator · high confidence

The bridge detection logic in \src/bridge\ has been restructured to improve accuracy for conditional \abi3\ features. Detection is now a two-phase process: \find\_bridge\ performs an initial conservative detection excluding conditional features, and \upgrade\_bridge\_stable\_abi\ refines the stable ABI selection after interpreter resolution. Additionally, the \Bindings\ input enum is now a single source of truth for CLI and configuration parsing, ensuring consistent handling of \pyo3\, \pyo3-ffi\, \cffi\, \uniffi\, and \bin\ binding types.

src/bridge · high confidence

The command-line interface has been reorganized by moving subcommands into separate modules (build, develop, generate\_stubs, pep517, publish, sdist) to decouple build orchestration from the BuildContext. This refactor introduces a new \generate-stubs\ command that produces Python type stubs (.pyi) into the module's package directory, ensuring correct layout for type checkers. The PEP 517 backend now supports the \MATURIN\_PGO\ environment variable to enable Profile-Guided Optimization and includes fixes to prevent panics when duplicate interpreters are passed or when no interpreters match the abi3 minimum version. Additionally, the \develop\ command now robustly detects virtual environments by checking \VIRTUAL\_ENV\, \CONDA\_PREFIX\, or a \.venv\ directory in parent folders.

src/commands · high confidence

The CI configuration files for Travis CI (before\_deploy.sh, install.sh, and script.sh) have been deleted. This removes the automated steps for installing Rust toolchains, running tests, building binaries, and packaging releases that were previously handled by Travis CI.

ci · high confidence

The explicit requirement for the nightly Rust toolchain has been removed from the get\_fourtytwo package. Users can now build the project using the stable Rust toolchain, simplifying the development environment setup.

_get\fourtytwo · high confidence

The integration-test directory has removed the previous shell-based test suite (test\_versions.sh) and its associated Python entry point (main.py). This eliminates the manual workflow that built the package and verified it against isolated virtual environments for Python 2.7, 3.5, and 3.6, effectively dropping support for these older Python versions in the integration testing process.

integration-test · high confidence

The Python interpreter detection logic has been refactored into a unified pipeline that centralizes discovery, validation, and ABI tag calculation. This change introduces explicit support for free-threaded (GIL-disabled) CPython interpreters, correctly handling the 't' ABI flag and ensuring compatibility with Python 3.14+. It also improves cross-compilation support by using bundled sysconfig data as a fallback when real interpreters are unavailable, and adds better error reporting for missing or incompatible interpreters. The new system deduplicates found interpreters, filters them by target architecture and version constraints, and provides a consistent interface for generating PyO3 configuration files.

_src/python\interpreter · high confidence

The \pyo3-mixed-workspace\ crate now includes its Rust source file (\src/lib.rs\), which exposes the \get\_21\_lib\ function. This change ensures the library code is present in the source distribution (sdist), resolving the missing member issue that previously prevented the nested workspace layout from building correctly from source.

test-crates/pyo3-mixed-workspace/rust/pyo3-mixed-workspace · high confidence

Add Python binding test crate for workspace inheritance; Add cffi-mixed-implicit test fixture; Add check\_installed validation script for pyo3-mixed test crate; Add integration test infrastructure for CLI, Emscripten/Pyodide, and manylinux builds; Add pyo3-ffi-pure test crate for low-level FFI module initialization; Add pyo3-mixed test crate for mixed Rust/Python projects; Add pyo3\_mixed test crate with Python module and Rust bindings; Add test case for uniffi with multiple crates; Add test crate for PyO3 CFFI build script stability; Add test crate for combining PyO3 abi3 and abi3t features; Add test crate for external Python source support; Add test crate for inverted workspace structure; Add test crate for mixed PyO3 stub generation; Add test crate for nested PyO3 workspace layout; Add test fixtures for PyO3 workspace binding detection; Add test fixtures for parent workspace sdist generation; Add verification script for pure Rust PyO3 package installation; Added CFFI integration test fixtures; Added empty test crate for missing python-source validation; Added empty test crate for pyo3 abi3 without version; Added initial test for pyo3\_mixed.get\_42; Added license-test crate for validating installed license detection; Added test case for UniFFI multi-crate support; Added test case for source distribution readme duplication; Added test crate for OUT\_DIR asset inclusion; Added test crate for PyO3 FFI usage without extension-module; Added test crate for UniFFI multi-crate binding generation; Added test crate for binary projects with Python modules; Added test crate for disallowed library linking; Added test crate for sdist with target path dependency; Added test crate for validating local path dependencies; Added test crate for validating wheel data and header installation; Added test crates for PyO3 abi3t features on Python 3.15; Added test crates for PyO3 stub generation; Added tests for pyo3-pure module functionality; Added transitive\_lib test crate; Expanded integration and regression test coverage for develop, sdist, and wheel workflows; New test crate for sdist with path dependency; Refactored test harness with table-driven scenarios and shared infrastructure; Snapshot tests added for CLI help output.

The project now includes a pyproject.toml file to bootstrap the maturin package itself on non-manylinux platforms, specifying build requirements like setuptools and setuptools-rust. Additionally, a comprehensive set of test crates has been added under test-crates/ to validate various build scenarios, including CFFI bindings, PyO3 binaries, mixed Python/Rust modules, workspace inheritance, and ABI3 features.

(dependencies) · high confidence

Written by watchdog.canine.dev from the codebase's own history, inside the signed delivery this page is composed from.

• CAI 73 → 72 (-1.1)
• Rubric changed (rubric-2026.09.10 → rubric-2026.09.18) — scores are not directly comparable.

• Code Health 82 → 82 (-0.1)
• Architecture 98 → 98 (+0.7)
• Maturity 66 → 66 (+0.3)
• Readiness 79 → 72 (-6.9)
• Security 75 → 80 (+4.6)
• Performance 86 (new)

• Documentation: no installation or build instructions (README.md)
• Documentation: no usage examples (README.md)
• Hotspot: src/auditwheel/linux.rs (src/auditwheel/linux.rs)
• Hotspot: src/cargo_options.rs (src/cargo_options.rs)
• Hotspot: src/cross_compile.rs (src/cross_compile.rs)
• Hotspot: src/metadata.rs (src/metadata.rs)
• Hotspot: src/module_writer/mod.rs (src/module_writer/mod.rs)
• Hotspot: src/python_interpreter/config.rs (src/python_interpreter/config.rs)
• Off-boarding risk: anonymized user #1
• Repeated repair: src/build_options.rs (src/build_options.rs)
• Repeated repair: src/python_interpreter/mod.rs (src/python_interpreter/mod.rs)

• Duplicated block (6 lines × 2) (maturin/init.py)
• Inconsistent accessor style: PyProjectToml exposes many configuration fields via methods (e.g., maturin(), module_name(), strip()) rather than properties. While this might be intentional for lazy loading or validation, it is inconsistent with standard Rust/Python idioms where simple data retrieval is a property. Furthermore, module_name() returns str while module_name in ProjectContext is String (Rust) or similar, but the method signature str vs String in the API surface description suggests potential type inconsistency or boxing/unboxing overhead not visible in signatures but implied by naming.
• Inconsistent naming in PEP 517 interface: build_wheel and build_sdist are standard, but build_editable is non-standard (PEP 660 uses build_editable but often as a separate entry point or method). More critically, prepare_metadata_for_build_wheel is standard, but there is no prepare_metadata_for_build_sdist. This is an API design choice, not necessarily an inconsistency, but the mix of 'build' and 'prepare' verbs is slightly disjointed.
• Naming inconsistency in builder pattern: BuildOptions uses into_build_context() which returns a BuildContextBuilder, but the resulting type is a Builder, not the Context itself. This suggests a confusing flow where 'into' implies consumption/conversion to the final object, but it yields an intermediate builder.
• Naming inconsistency: check_executable (singular) vs check_executables (plural). The singular version takes a single path, the plural takes a slice. This is a minor inconsistency but breaks the pattern of find_all vs find if such existed. It is acceptable but could be cleaner.
• Off-boarding risk: anonymized user #1
• Outdated: anyhow
• Outdated: bytesize
• Outdated: cargo-config2
• Outdated: cargo-zigbuild
• Outdated: cbindgen
• Outdated: cc
• Outdated: clap
• Outdated: configparser
• Outdated: console
• Outdated: flate2
• Outdated: fs-err
• Outdated: glob
• Outdated: goblin
• Outdated: ignore
• …and 21 more

• 7 commits — 6 feature/other, 1 fixes

• (root) — 3 commits
• src/python_interpreter — 2 commits
• .config/nextest.toml — 1 commit
• src/module_writer — 1 commit

• fix: fix: lossy-decode external command output in interpreter discovery (#3302)
• change: Include SOABI_PLATFORM in Python 3.15 stable ABI extension filenames (#3305)
• change: Sort compressed tag sets (#3315)
• change: [pre-commit.ci] pre-commit autoupdate (#3303)
• change: [pre-commit.ci] pre-commit autoupdate (#3309)
• change: build(deps): update rustls for RUSTSEC-2026-0285 (#3308)
• change: ci: run conda tests one at a time (#3311)

Written by watchdog.canine.dev from the codebase's own history, inside the signed delivery this page is composed from.

PyO3/maturin was measured the same way every project in this corpus was: the same rubric, at a pinned commit, with the result published in full. Point a surveyor at a repository you know and see whether you agree with it.