Principle:Nautechsystems Nautilus trader Maturin Build Configuration
| Knowledge Sources | |
|---|---|
| Domains | Build_Tooling, Python, Rust |
| Last Updated | 2026-02-10 08:00 GMT |
Overview
A build approach that uses maturin to compile Rust PyO3 crates directly into Python extension modules, replacing custom build scripts with a standardized Rust-Python build pipeline.
Description
Maturin Build Configuration represents a modern alternative to the traditional custom build.py approach for Rust-Python hybrid packages. Instead of manually invoking cargo build and managing library paths, maturin handles the entire pipeline: compiling the Rust crate, generating the Python extension module, and packaging it into a wheel. Configuration is declarative in pyproject.toml rather than imperative in a build script. Key configuration points include: (1) manifest-path pointing to the Rust crate's Cargo.toml. (2) module-name specifying the Python import path for the compiled extension. (3) features enabling specific Rust feature flags (database backends, precision modes, tracing). (4) pre-build hooks for running stub generation before compilation. This approach simplifies cross-platform builds, reduces build script maintenance, and integrates with standard Python packaging tools.
Usage
Apply this principle when a Python package is primarily backed by Rust via PyO3 and the build does not require Cython compilation. Maturin is preferred over custom build scripts when the Rust extension is the only compiled component, as it handles cross-compilation, wheel creation, and PEP 517 compliance automatically.
Theoretical Basis
Maturin follows a declarative build configuration model:
# Abstract build model (NOT real implementation)
config = parse_pyproject_toml("pyproject.toml")
# Pre-build hook (e.g., stub generation)
run_script(config.maturin.scripts.pre_build)
# Maturin handles everything:
cargo_build(
manifest=config.maturin.manifest_path,
features=config.maturin.features,
target=python_abi_tag(),
)
# Package into wheel
wheel = create_wheel(
extension=compiled_so,
stubs=config.maturin.include,
metadata=config.project,
)
Advantages over custom build scripts:
- Declarative — configuration in TOML, not imperative Python
- Cross-compilation — maturin handles platform-specific ABI tags
- PEP 517 compliant — works with pip install without workarounds
- Standardized — no custom code to maintain for cargo invocation