ghcr.io/pyo3/maturin:v1.13.3-musllinux

Maturin

formerly pyo3-pack

使用最少的配置构建和发布带有 pyo3、cffi 和 uniffi 绑定 的 crate，以及将 Rust 二进制文件作为 Python 包发布。它支持在 Windows、Linux、macOS 和 FreeBSD 上为 Python 3.8+ 构建 wheel，可将其上传到 pypi，并基本支持 PyPy 和 GraalPy。

查看 用户指南！

用法

# pipx
pipx install maturin
# uv
uv tool install maturin

[!NOTE]

如果你不想使用 pipx，pip install maturin 也可以正常工作。

有三个主要命令：

• maturin new 创建一个配置了 maturin 的新 cargo 项目。
• maturin build 构建 wheel 并将其存储在文件夹中（默认是 target/wheels），但不会上传。建议使用 https://github.com/astral-sh/uv 通过 uv publish 发布包。
• maturin develop 构建 crate 并将其作为 Python 模块直接安装到当前 virtualenv 中。注意，虽然 maturin develop 速度更快，但它不支持 maturin build 后运行 pip install 所支持的所有功能。

maturin 不需要额外的配置文件，也不会与现有的 setuptools-rust 配置冲突。你甚至可以将其与 tox 等测试工具集成。test-crates 文件夹中包含不同绑定的示例。

包的名称将是 cargo 项目的名称，即 Cargo.toml 中 [package] 部分的 name 字段。导入时使用的模块名称将是 [lib] 部分的 name 值（默认为包的名称）。对于二进制文件，它就是 cargo 生成的二进制文件的名称。

使用 maturin build 和 maturin develop 命令时，你可以通过添加 -r 或 --release 标志来编译性能优化的程序。

Python 打包基础

Python 包有两种格式：一种称为 wheel 的构建形式和源代码分发版（sdist），两者都是归档文件。wheel 可以与任何 Python 版本、解释器（主要是 CPython 和 PyPy）、操作系统和硬件架构兼容（对于纯 Python wheel），也可以限制在特定平台和架构（例如使用 ctypes 或 cffi 时），或者特定架构和操作系统上的特定 Python 解释器和版本（例如使用 pyo3 时）。

使用 pip install 安装包时，pip 会尝试找到匹配的 wheel 并安装。如果找不到，它会下载源代码分发版并为当前平台构建 wheel，这需要安装正确的编译器。安装 wheel 比安装源代码分发版快得多，因为构建 wheel 通常很慢。

当你发布一个可通过 pip install 安装的包时，需要将其上传到 pypi（官方包仓库）。测试时，你可以使用 test pypi，可通过 pip install --index-url https://test.pypi.org/simple/ 使用。注意，对于 为 Linux 发布，你需要使用 manylinux Docker 容器或 zig，而从仓库发布时可以使用 https://github.com/PyO3/maturin-action GitHub Action。

混合 Rust/Python 项目

要创建混合 Rust/Python 项目，请在 Cargo.toml 旁边创建一个与模块名称（即 Cargo.toml 中的 lib.name）相同的文件夹，并在其中添加 Python 源代码：

my-project
├── Cargo.toml
├── my_project
│   ├── __init__.py
│   └── bar.py
├── pyproject.toml
├── README.md
└── src
   └── lib.rs

你可以在 pyproject.toml 中通过设置 tool.maturin.python-source 指定不同的 Python 源代码目录，例如：

pyproject.toml

[tool.maturin]
python-source = "python"
module-name = "my_project._lib_name"

此时项目结构如下：

my-project
├── Cargo.toml
├── python
│ └── my_project
│ ├── __init__.py
│ └── bar.py
├── pyproject.toml
├── README.md
└── src
   └── lib.rs

[!NOTE]

推荐使用此结构以避免 https://github.com/PyO3/maturin/issues/490

maturin 会将原生扩展作为模块添加到你的 Python 文件夹中。使用 develop 时，maturin 会将原生库以及 cffi 的胶水代码复制到 Python 文件夹中。你应该将这些文件添加到 .gitignore 中。

使用 cffi 时，你可以执行 from .my_project import lib，然后使用 lib.my_native_function；使用 pyo3 时，你可以直接 from .my_project import my_native_function。

使用 pyo3 执行 maturin develop 后的示例布局：

my-project
├── Cargo.toml
├── my_project
│   ├── __init__.py
│   ├── bar.py
│   └── _lib_name.cpython-36m-x86_64-linux-gnu.so
├── README.md
└── src
   └── lib.rs

此时还需确保代码中的模块名称与 module-name 的最后一部分匹配（不包含包路径）：

#[pymodule]
#[pyo3(name="_lib_name")]
fn my_lib_name(m: &Bound ) -> PyResult {
m.add_class:: ()?;
Ok(())
}

Python 元数据

maturin 支持 PEP 621，你可以在 pyproject.toml 中指定 Python 包元数据。maturin 会合并 Cargo.toml 和 pyproject.toml 中的元数据，pyproject.toml 的优先级高于 Cargo.toml。

要指定 Python 依赖项，请在 pyproject.toml 的 [project] 部分添加 dependencies 列表。此列表等效于 setuptools 中的 install_requires：

[project]
name = "my-project"
dependencies = ["flask~=1.1.0", "toml>=0.10.2, =1.0, =1.0,<2.0"]
build-backend = "maturin"

[tool.maturin]
bindings = "cffi"
compatibility = "linux"

为了与旧版本 maturin 向后兼容，manylinux 选项也可作为 compatibility 的别名。

要在 sdist 中包含编译时使用的任意文件，请将 include 指定为包含 path 通配符且 format 设置为 sdist 的数组：

[tool.maturin]
include = [{ path = "path/**/*", format = "sdist" }]

有一个 maturin sdist 命令用于仅构建源代码分发版，作为 https://github.com/pypa/pip/issues/6041 的解决方法。

Manylinux 和 auditwheel

出于可移植性考虑，Linux 上的原生 Python 模块必须仅动态链接一组几乎在所有地方都安装的极少数库，因此得名 manylinux。PyPA 提供了特殊的 Docker 镜像和一个名为 https://github.com/pypa/auditwheel/ 的工具，以确保符合 manylinux 规则。如果你想为 Linux PyPI 发布广泛可用的 wheel，你需要使用 manylinux Docker 镜像或通过 zig 构建。

自 1.64 版本起，Rust 编译器要求至少 glibc 2.17，因此你需要使用至少 manylinux2014。 发布时，我们建议使用 manylinux 标志强制与镜像相同的 manylinux 版本，例如，如果你在 quay.io/pypa/manylinux2014_x86_64 中构建，使用 --manylinux 2014。 如果你设置 manylinux: 2014 等参数，https://github.com/PyO3/maturin-action GitHub Action 会自动处理此问题。

maturin 包含 auditwheel 的重新实现，可自动检查生成的库并为 wheel 分配正确的平台标签。 如果你的系统 glibc 版本过新或链接了其他共享库，它会分配 linux 标签。 你也可以手动禁用这些检查，使用 --manylinux off 直接使用原生 linux 目标。

要完全符合 manylinux 标准，你需要在 CentOS docker 容器中编译。pyo3/maturin 镜像基于 manylinux2014 镜像，并将参数传递给 maturin 二进制文件。你可以这样使用：

docker run --rm -v $(pwd):/io ghcr.io/pyo3/maturin build --release # 或其他 maturin 参数

[!NOTE] 此镜像非常基础，仅包含 python、maturin 和 stable rust。如果需要其他工具，可以在 manylinux 容器内运行命令。 有关小型教学示例，请参见 https://github.com/konstin/complex-manylinux-maturin-docker%EF%BC%9B%E6%9C%89%E5%85%B3%E5%AE%9E%E9%99%85%E5%BA%94%E7%94%A8%E8%AE%BE%E7%BD%AE%EF%BC%8C%E8%AF%B7%E5%8F%82%E8%A7%81 https://github.com/nanoporetech/fast-ctc-decode/blob/b226ea0f2b2f4f474eff47349703d57d2ea4801b/.github/workflows/publish.yml%E3%80%82

当编译为 musl 目标时，maturin 本身符合 manylinux 标准。

示例

• agg-python-bindings - 一个绑定到 Asciinema Agg 终端记录渲染器和 Avt 终端模拟器的 Python 库
• https://github.com/apache/arrow-ballista-python - 一个绑定到 Apache Arrow 分布式查询引擎 Ballista 的 Python 库
• https://github.com/shenxiangzhuang/bleuscore - 一个纯 Rust 编写的 BLEU 分数计算库
• https://github.com/john-parton/chardetng-py - chardetng 字符编码检测器的 Python 绑定
• https://github.com/sfu-db/connector-x/tree/main/connectorx-python - ConnectorX 让你能以最快、最内存高效的方式将数据库数据加载到 Python 中
• https://github.com/apache/arrow-datafusion-python - 一个绑定到 Apache Arrow 内存中查询引擎 DataFusion 的 Python 库
• https://github.com/delta-io/delta-rs/tree/main/python - 基于 delta-rs 的原生 Delta Lake Python 绑定，支持 Pandas 集成
• https://github.com/apache/incubator-opendal/tree/main/bindings/python - OpenDAL Python 绑定，用于自由访问数据
• https://github.com/ijl/orjson - 一个快速、正确的 Python JSON 库
• https://github.com/pola-rs/polars/tree/master/py-polars - Rust | Python | Node.js 中的快速多线程 DataFrame 库
• https://github.com/pydantic/pydantic-core - pydantic 的核心验证逻辑，用 Rust 编写
• https://github.com/milesgranger/pyrus-cramjam - Rust 中压缩/解压缩算法的轻量级 Python 包装器
• https://github.com/kitao/pyxel - 一个用于 Python 的复古游戏引擎
• https://github.com/roapi/roapi - ROAPI 自动为静态数据集启动只读 API，无需编写任何代码
• https://github.com/sansyrox/robyn - 一个基于 Rust 运行时的快速且可扩展的异步 Python Web 服务器
• https://github.com/charliermarsh/ruff - 一个极快的 Python 代码检查器，用 Rust 编写
• https://github.com/0x676e67/rnet - 具有黑魔法的异步 Python HTTP 客户端
• https://github.com/rahmadafandi/rustpy-xlsxwriter - 一个高性能的 Excel 文件生成 Python 库，利用 https://github.com/jmcnamara/rust_xlsxwriter crate 进行高效数据处理
• https://github.com/quickwit-oss/tantivy-py - Tantivy 的 Python 绑定
• https://github.com/clflushopt/tpchgen-rs/tree/main/tpchgen-cli - tpchgen 的 Python CLI 绑定，tpchgen 是一个纯 Rust 编写、零依赖的极速 TPC-H 基准数据生成器
• https://github.com/samuelcolvin/watchfiles - Python 中简单、现代且高性能的文件监视和代码重载工具
• https://github.com/webonnx/wonnx/tree/master/wonnx-py - Wonnx 是一个 100% 用 Rust 编写的 GPU 加速 ONNX 推理运行时

贡献

欢迎所有人为 maturin 做贡献！支持项目的方式有很多，例如：

• 在 GitHub 和 Gitter 上帮助 maturin 用户解决问题
• 改进文档
• 编写功能和修复 bug
• 发布关于如何使用 maturin 的博客和示例

如果你希望为 maturin 贡献时间并正在寻找起点，我们的https://github.com/PyO3/maturin/blob/main/guide/src/contributing.md%E6%8F%90%E4%BE%9B%E4%BA%86%E6%9B%B4%E5%A4%9A%E8%B5%84%E6%BA%90%E3%80%82

如果你没有时间亲自贡献，但仍希望支持项目的未来发展，我们的一些维护者设有 GitHub 赞助页面：

• https://github.com/***/messense

许可协议

采用以下任一许可协议：

• Apache License, Version 2.0（https://github.com/PyO3/maturin/blob/main/license-apache 或 [***] - 2.0）
• MIT 许可协议（https://github.com/PyO3/maturin/blob/main/license-mit 或 [***]

由你选择。