maturin

Construa e publique wheels Python que empacotam extensões Rust com maturin.

Receita

# pyproject.toml
[build-system]
requires = ["maturin>=1.8"]
build-backend = "maturin"
 
[project]
name = "myrust"
requires-python = ">=3.10"

maturin develop --release

Quando usar isso: Enviar extensões PyO3 para o PyPI ou índices de pacotes internos com ferramentas Python padrão.

Exemplo de Trabalho

# Cargo.toml
[package]
name = "myrust"
version = "0.1.0"
edition = "2024"
 
[lib]
name = "myrust"
crate-type = ["cdylib"]
 
[dependencies]
pyo3 = { version = "0.23", features = ["extension-module"] }

# pyproject.toml
[tool.maturin]
module-name = "myrust"
python-source = "python"
features = ["pyo3/extension-module"]

python/
  myrust/
    __init__.py   # re-exporta

maturin build --release --out dist
pip install dist/myrust-0.1.0-*.whl

O que isso demonstra:

O tipo de crate cdylib produz o módulo nativo
O recurso extension-module informa ao PyO3 que ele está sendo carregado pelo Python
maturin develop instala no venv ativo para iteração rápida
maturin build emite wheels específicos da plataforma em dist/

Mergulho Profundo

Comandos

Comando	Uso
`maturin develop`	Instalação editável local
`maturin build`	Produz wheels para CI
`maturin publish`	Envia para o PyPI
`maturin generate-ci`	Modelo do GitHub Actions

abi3 Wheels

[dependencies]
pyo3 = { version = "0.23", features = ["extension-module", "abi3-py39"] }

Um wheel por plataforma cobre Python 3.9+.

Layout Misto Python + Rust

my-package/
  Cargo.toml
  pyproject.toml
  python/mypkg/__init__.py
  src/lib.rs

Armadilhas

Venv ausente - Instala no Python errado. Correção: Ative o venv antes de maturin develop.
Conformidade Manylinux - Wheels Linux devem ser construídos em imagens base compatíveis. Correção: Use maturin build --compatibility manylinux_2_28 ou imagens Docker de CI.
macOS universal2 - Apple Silicon + Intel precisam de wheels "fat". Correção: maturin build --target universal2-apple-darwin.
SDist sem Rust - Usuários do tarball de origem precisam da toolchain Rust. Correção: Publique wheels para todas as plataformas suportadas.
Arquivos de licença - PyPI requer metadados. Correção: Defina license em pyproject.toml e inclua LICENSE no manifesto.

Alternativas

Alternativa	Use Quando	Não Use Quando
`setuptools-rust`	Fluxos de trabalho setuptools legados	Novos projetos PyO3
`cffi` + dll pré-compilado	Usuários não podem compilar Rust	Você controla todas as plataformas
`uv build` com backend maturin	Empacotamento Python moderno	N/A para extensões Rust

FAQs

maturin vs pip install .?

maturin entende o layout Rust e os recursos PyO3. O pip simples pode perder etapas de compilação de extensão.

Compatibilidade com Poetry?

Use maturin como backend PEP 517. Poetry gerencia dependências; maturin constrói a extensão.

uv e maturin?

uv pip install funciona em wheels construídos com maturin. uv sync em repositórios híbridos precisa do fluxo de trabalho de desenvolvimento documentado.

PyPI Privado?

maturin publish --repository-url https://internal/simple/.

Depender de outros crates Rust?

Dependências normais do Cargo. maturin executa cargo build internamente.

Incluir stubs Python puros?

Coloque arquivos .pyi no pacote python/ para verificadores de tipo.

Compilar cruzado Windows a partir de Linux?

Use toolchains cruzadas e sinalizadores de destino do maturin na matriz de CI.

Builds de depuração?

maturin develop sem --release para compilações mais rápidas; tempo de execução mais lento.

Workspace Cargo.toml?

maturin suporta workspaces com manifest-path apontando para o crate de extensão.

Auditar wheels?

pip audit e cargo deny para verificações de cadeia de suprimentos de dupla linguagem.

Relacionado

PyO3 - código de extensão
Noções Básicas de Interoperabilidade - estratégia Python
Marshalling de Dados - tipos de buffer Python
Melhores Práticas de Interoperabilidade - higiene de lançamento

Versões da Stack: Esta página foi escrita para Rust 1.97.0 (edição 2024), Tokio 1.x, Axum 0.8, serde 1.0, sqlx 0.8, clap 4, e Polars 0.46+.

maturin

Construa e publique wheels Python que empacotam extensões Rust com maturin.

Receita

# pyproject.toml
[build-system]
requires = ["maturin>=1.8"]
build-backend = "maturin"
 
[project]
name = "myrust"
requires-python = ">=3.10"

maturin develop --release

Quando usar isso: Enviar extensões PyO3 para o PyPI ou índices de pacotes internos com ferramentas Python padrão.

Exemplo de Trabalho

# Cargo.toml
[package]
name = "myrust"
version = "0.1.0"
edition = "2024"
 
[lib]
name = "myrust"
crate-type = ["cdylib"]
 
[dependencies]
pyo3 = { version = "0.23", features = ["extension-module"] }

# pyproject.toml
[tool.maturin]
module-name = "myrust"
python-source = "python"
features = ["pyo3/extension-module"]

python/
  myrust/
    __init__.py   # re-exporta

maturin build --release --out dist
pip install dist/myrust-0.1.0-*.whl

O que isso demonstra:

O tipo de crate cdylib produz o módulo nativo
O recurso extension-module informa ao PyO3 que ele está sendo carregado pelo Python
maturin develop instala no venv ativo para iteração rápida
maturin build emite wheels específicos da plataforma em dist/

Mergulho Profundo

Comandos

Comando	Uso
`maturin develop`	Instalação editável local
`maturin build`	Produz wheels para CI
`maturin publish`	Envia para o PyPI
`maturin generate-ci`	Modelo do GitHub Actions

abi3 Wheels

[dependencies]
pyo3 = { version = "0.23", features = ["extension-module", "abi3-py39"] }

Um wheel por plataforma cobre Python 3.9+.

Layout Misto Python + Rust

my-package/
  Cargo.toml
  pyproject.toml
  python/mypkg/__init__.py
  src/lib.rs

Armadilhas

Venv ausente - Instala no Python errado. Correção: Ative o venv antes de maturin develop.
Conformidade Manylinux - Wheels Linux devem ser construídos em imagens base compatíveis. Correção: Use maturin build --compatibility manylinux_2_28 ou imagens Docker de CI.
macOS universal2 - Apple Silicon + Intel precisam de wheels "fat". Correção: maturin build --target universal2-apple-darwin.
SDist sem Rust - Usuários do tarball de origem precisam da toolchain Rust. Correção: Publique wheels para todas as plataformas suportadas.
Arquivos de licença - PyPI requer metadados. Correção: Defina license em pyproject.toml e inclua LICENSE no manifesto.

Alternativas

Alternativa	Use Quando	Não Use Quando
`setuptools-rust`	Fluxos de trabalho setuptools legados	Novos projetos PyO3
`cffi` + dll pré-compilado	Usuários não podem compilar Rust	Você controla todas as plataformas
`uv build` com backend maturin	Empacotamento Python moderno	N/A para extensões Rust

FAQs

maturin vs pip install .?

maturin entende o layout Rust e os recursos PyO3. O pip simples pode perder etapas de compilação de extensão.

Compatibilidade com Poetry?

Use maturin como backend PEP 517. Poetry gerencia dependências; maturin constrói a extensão.

uv e maturin?

uv pip install funciona em wheels construídos com maturin. uv sync em repositórios híbridos precisa do fluxo de trabalho de desenvolvimento documentado.

PyPI Privado?

maturin publish --repository-url https://internal/simple/.

Depender de outros crates Rust?

Dependências normais do Cargo. maturin executa cargo build internamente.

Incluir stubs Python puros?

Coloque arquivos .pyi no pacote python/ para verificadores de tipo.

Compilar cruzado Windows a partir de Linux?

Use toolchains cruzadas e sinalizadores de destino do maturin na matriz de CI.

Builds de depuração?

maturin develop sem --release para compilações mais rápidas; tempo de execução mais lento.

Workspace Cargo.toml?

maturin suporta workspaces com manifest-path apontando para o crate de extensão.

Auditar wheels?

pip audit e cargo deny para verificações de cadeia de suprimentos de dupla linguagem.

Relacionado

PyO3 - código de extensão
Noções Básicas de Interoperabilidade - estratégia Python
Marshalling de Dados - tipos de buffer Python
Melhores Práticas de Interoperabilidade - higiene de lançamento

Versões da Stack: Esta página foi escrita para Rust 1.97.0 (edição 2024), Tokio 1.x, Axum 0.8, serde 1.0, sqlx 0.8, clap 4, e Polars 0.46+.

maturin

Buscar na documentação

maturin