ghcr.io/pyo3/maturin:v1.9.4

Maturin

（前身为 pyo3-pack）

使用最少配置构建和发布带有 pyo3、cffi 和 uniffi 绑定 的 crate，以及将 Rust 二进制文件作为 Python 包发布。它支持为 Windows、Linux、macOS 和 FreeBSD 上的 Python 3.8+ 构建 wheel，可将其上传到 https://pypi.org/%EF%BC%8C%E5%B9%B6%E5%9F%BA%E6%9C%AC%E6%94%AF%E6%8C%81 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 模块直接安装到当前虚拟环境中。注意，虽然 maturin develop 速度更快，但它不支持 maturin build 后运行 pip install 所支持的所有功能。

maturin 不需要额外的配置文件，也不会与现有的 setuptools-rust 配置冲突。你甚至可以将其与 https://tox.readthedocs.io/en/latest/ 等测试工具集成。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 安装的包时，需将其上传到官方包仓库 https://pypi.org/%E3%80%82%E6%B5%8B%E8%AF%95%E6%97%B6%EF%BC%8C%E5%8F%AF%E4%BB%A5%E4%BD%BF%E7%94%A8 https://test.pypi.org/ 替代，可通过 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 旁边创建一个与模块名称（即 https://doc.rust-lang.org/cargo/reference/cargo-targets.html#the-name-field%EF%BC%89%E7%9B%B8%E5%90%8C%E7%9A%84%E6%96%87%E4%BB%B6%E5%A4%B9%EF%BC%8C%E5%B9%B6%E5%9C%A8%E5%85%B6%E4%B8%AD%E6%B7%BB%E5%8A%A0 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 会将原生库复制到 Python 文件夹中，对于 cffi 还会复制粘合代码。你应该将这些文件添加到 .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(())
}

自 1.64 版本起，Rust 编译器https://blog.rust-lang.org/2022/08/01/Increasing-glibc-kernel-requirements.html%EF%BC%8C%E5%9B%A0%E6%AD%A4%E6%82%A8%E8%87%B3%E5%B0%91%E9%9C%80%E8%A6%81%E4%BD%BF%E7%94%A8 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 容器中编译。https://ghcr.io/pyo3/maturin 镜像基于 manylinux2014 镜像，并将参数传递给 maturin 二进制文件。您可以这样使用：

docker run --rm -v $(pwd):/io ghcr.io/pyo3/maturin build --release # or other maturin arguments

[!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 标准。

示例

• https://pypi.org/project/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/ratazzi/pdfcrate - 一个用于 Rust 和 Python 的符合人体工程学的高级 PDF 生成库 — 提供类似 Prawn 的文档排版 API，而非底层 PDF 处理
• 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/ratazzi/quebec - 一个基于数据库的 Python 后台任务队列，灵感来自 Rails 的 Solid Queue
• 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 或 http://www.apache.org/licenses/LICENSE-2.0%EF%BC%89
• MIT 许可（https://github.com/PyO3/maturin/blob/main/license-mit 或 http://opensource.org/licenses/MIT%EF%BC%89

您可以选择任一许可。