maturin 用户指南全览：从零构建、打包与发布 Rust/Python 混合项目

开发工具构建工具【免费下载链接】maturinBuild and publish crates with pyo3, cffi and uniffi bindings as well as rust binaries as python packages项目地址https://gitcode.com/gh_mirrors/ma/maturin点击查看免费下载导读maturin 是一个用于构建并发布 Python 包的工具它把 Rust crate通过 pyo3、cffi、uniffi 绑定以及纯 Rust 二进制打包成标准的 wheel 与 sdist 发行物。本文以官方用户指南guide/src/index.md其中内嵌 README为主线完整梳理安装方式、三大核心命令、Python 打包基础、混合项目布局、PEP 621 元数据、源码发行版与 manylinux 兼容策略并结合仓库源码说明底层实现帮助读者一次性建立起使用 maturin 构建可发布 Python 包的全流程能力。一、maturin 是什么maturin前身名为 pyo3-pack是一个构建与发布工具它支持将带有 pyo3、cffi、uniffi 绑定 的 crate以及纯 Rust 二进制程序以最小化配置的方式构建成 Python 包。它可以在 Windows、Linux、macOS 和 FreeBSD 上为 Python 3.8 构建 wheel支持上传到 PyPI并提供基础的 PyPy 与 GraalPy 支持。从 源码入口 可以看到maturin 的 CLI 定义了完整的命令集build、publish、list-python、develop、sdist、init、new、generate-ci、upload、generate-stubs、pep517等其中build与develop是日常开发最常用的两个命令。maturin 不需要额外的配置文件也不会与已有的 setuptools-rust 配置冲突。官方在test-crates目录下提供了针对不同绑定类型pyo3、cffi、uniffi、bin的完整示例工程可供对照学习。二、安装 maturin官方用户指南在 安装章节 中提供了多种安装途径2.1 通过 pipx / uv / pip 安装maturin 以 Python 二进制 wheel 的形式发布到 PyPI推荐使用 pipx 或 uv 安装# pipx pipx install maturin # uv uv tool install maturin如果不想使用 pipxpip install maturin也可以正常工作。针对特定场景还有两个可选的附加依赖zig使用 zig 作为链接器便于交叉编译和实现 manylinux 兼容patchelf修复链接了其他共享库的 wheel。例如安装 patchelf 依赖pipx install maturin[patchelf]。2.2 系统包管理器HomebrewmacOSbrew install maturin。注意Homebrew 安装会顺带安装一份独立的 Rust如果你已经通过 rustup 安装了 Rust会形成两份安装并可能产生冲突此时建议改用其他方式安装condaconda-forge 频道先执行conda config --add channels conda-forge和conda config --set channel_priority strict再执行conda install maturinAlpine Linux启用 community 仓库后执行apk add maturin。2.3 从源码构建使用 cargo 从 crates.io 安装带--locked保证依赖锁定cargo install --locked maturin也可以直接从 Git 仓库安装。提示如果从源码自行构建 maturin且需要 SBOM软件物料清单支持可参考 SBOM 章节 启用sbomfeature。三、三大核心命令maturin 有三条主要命令定义于 src/main.rsmaturin new创建一个已配置好 maturin 的 Cargo 项目maturin build构建 wheel 并存放于指定目录默认是target/wheels但不执行上传适合产出可分发产物maturin develop构建 crate 并直接安装为当前 virtualenv 中的 Python 模块。注意maturin develop更快但支持的功能不如maturin build之后再用pip install完整。使用maturin build和maturin develop时可以添加-r或--release标志编译出性能优化版本。包的名称取自 Cargo 项目的name即Cargo.toml中[package]段的name字段你在import时使用的模块名则是[lib]段的name值默认为包名。对于二进制程序模块名就是 cargo 生成的二进制名称。3.1maturin new快速创建项目maturin new -b pyo3 guessing_game可以一键生成 pyo3 工程骨架命令支持的选项包括Usage: maturin new [OPTIONS] PATH Arguments: PATH 项目路径 Options: --name NAME 设置生成的包名默认使用目录名 --mixed 使用混合 Rust/Python 项目布局 --src 对混合项目使用 Python-first 的 src 布局 -b, --bindings BINDINGS 绑定类型[pyo3, cffi, uniffi, bin]四、Python 打包基础wheel 与 sdistPython 包有两种格式这一背景在 README 与用户指南的 项目布局、发行 章节中均有阐述wheel已构建的二进制发行物。wheel 可能对任意 Python 版本、解释器主要是 CPython 和 PyPy、操作系统和硬件架构通用纯 Python wheel也可能被限定到特定平台与架构如使用 ctypes 或 cffi 时或限定到特定架构与操作系统上的特定 Python 解释器与版本如使用 pyo3 时sdist源码发行物source distribution。当执行pip install时pip 会先尝试寻找匹配的 wheel 并直接安装找不到时才下载 sdist 并在当前平台现场构建 wheel这要求本机装有正确的编译器。安装 wheel 远比安装 sdist 快因为构建 wheel 通常很慢。发布到pip install可用的包时需要上传到官方包仓库 PyPI测试阶段可使用 test PyPI通过pip install --index-url https://test.pypi.org/simple/安装。注意要在 Linux 上发布详见后面的 manylinux 章节需要使用 manylinux Docker 容器或 zig 进行构建。五、混合 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.rspyproject.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官方推荐这种结构以避免一个常见的ImportError陷阱。maturin 会把原生扩展作为一个模块加入 Python 目录。使用maturin develop时maturin 会复制原生库cffi 场景下还有胶水代码到 Python 目录——这些生成的文件应当加入.gitignore。导入方式上cffi 可以from .my_project import lib后调用lib.my_native_functionpyo3 可以直接from .my_project import my_native_function。5.1 将 Rust 模块作为项目的子模块导入如果 Rust 生成的 Python 模块与混合项目中的 Python 包同名IDE 可能会混淆。可以通过module-name 包名.rust 模块名让 Rust 扩展以子模块形式安装[tool.maturin] module-name my_project._my_project同时更新lib.rs中的模块名pyo3 绑定下还可以用#[pyo3(name _my_project)]注解#[pymodule] #[pyo3(name _my_project)] fn my_project(...)随后在 Python 源码中导入from my_project import _my_project。这样 IDE 就能把_my_project识别为独立的模块某些 IDE 下还能获得 Rust 模块内类型的代码补全。5.2 Python 类型信息type stubs纯 Rust 项目在项目根目录放一个module_name.pyi文件maturin 会自动把它连同必需的py.typed标记文件一起打包混合项目在 Python 包根目录自行添加py.typed空文件并把.pyi桩文件放在对应位置。六、Python 元数据PEP 621maturin 支持 PEP 621。maturin 会合并Cargo.toml与pyproject.toml的元数据pyproject.toml优先级更高。6.1 声明 Python 依赖在[project]段添加dependencies列表等价于 setuptools 的install_requires[project] name my-project dependencies [flask~1.1.0, toml0.10.2,0.11.0]6.2 添加 console scripts[project.scripts]段可以声明可执行命令键为脚本名值为some.module.path:class.function格式class部分可选函数以无参方式调用[project.scripts] get_42 my_project:DummyClass.get_426.3 添加 trove classifiers[project] name my-project classifiers [Programming Language :: Python]6.4 动态元数据当pyproject.toml中没有[project]段时maturin 会从Cargo.toml填充name、versionSemVer 转 PEP 440、summary、description取自package.readme指定的 README、keywords、home_page、author、author_email、license、project_url等字段。当存在[project]段时必须至少包含name字段按照规范maturin 只能填充出现在project.dynamic列表中的字段。例如想让 Python 包版本跟随 Rust crate 版本需要把version加入dynamic列表[project] name my-awesome-project dynamic [ version, description, readme, urls, authors, license, keywords, ]七、源码发行版sdist与 PEP 517/518 集成maturin 支持通过pyproject.toml走 PEP 517 构建流程。在Cargo.toml旁创建pyproject.toml并写入[build-system] requires [maturin1.0,2.0] build-backend maturin当存在带[build-system]的pyproject.toml时指定--sdist即可构建源码发行版其内容与cargo package相同只构建 sdist 时可使用maturin sdist命令。之后便可通过pip install .安装加-v可以看到 cargo 与 maturin 的输出。PEP 517 的 Python 侧实现位于 maturin/init.py它通过子进程调用maturin pep517 build-wheel/write-sdist/write-dist-info并支持通过MATURIN_PEP517_ARGS环境变量或 pip 的--config-settings传递额外参数。在[tool.maturin]下可以像直接运行 maturin 一样使用compatibility、skip-auditwheel、bindings、strip以及features等 Cargo 构建选项。bindings键对 cffi 和 bin 项目是必需的因为这两类无法自动检测。当前 PEP 517 构建均采用 release 模式。例如一个非 manylinux 的 cffi 构建[build-system] requires [maturin1.0,2.0] build-backend maturin [tool.maturin] bindings cffi compatibility linuxmanylinux选项作为compatibility的别名保留用于向后兼容旧版本。要在 sdist 中包含编译所需的任意文件可用带format的 glob 配置[tool.maturin] include [{ path path/**/*, format sdist }]八、Manylinux 与 auditwheel出于可移植性考虑Linux 上的原生 Python 模块只能动态链接一组几乎处处安装的库这就是 manylinux 名称的由来对应 发行章节 的完整说明。如果想在 PyPI 发布广泛可用的 Linux wheel必须使用 manylinux Docker 镜像或使用 zig 构建。关键事实与策略Rust 编译器自 1.64 起要求至少 glibc 2.17因此至少要使用 manylinux2014发布时建议用 manylinux 标志强制与镜像一致的版本例如在quay.io/pypa/manylinux2014_x86_64中构建时使用--manylinux 2014maturin 内置了 auditwheel 的重新实现自动检查生成的库并给 wheel 打上正确的平台标签。若系统 glibc 过新或链接了其他共享库则会被标记为linux标签可以使用--manylinux off手动关闭检查直接使用原生 Linux 目标发布到 PyPI 时--compatibility pypi只允许构建 PyPI 接受的标签拒绝不支持的 OS 与架构。maturin build相关的兼容性选项完整清单定义于 build_options.rs--compatibility tag控制平台标签与 PyPI 兼容性可取值包括pypi、manylinux标签如manylinux2014/manylinux_2_24、musllinux标签如musllinux_1_2以及原生linux标签。注意manylinux1与manylinux2010不受 Rust 编译器支持原生linux标签会被 PyPI 拒绝除非另行通过 auditwheel 验证。默认取可兼容的最低 manylinux 标签无匹配时退回linux--auditwheel MODE取值为repair审计并修复、check只检查不修复、warn告警不失败不修复、skip跳过检查--zig对 manylinux 目标使用 zig 保证所选 manylinux 版本的兼容性需先pip install maturin[zig]-o, --out OUTwheel 输出目录默认是项目 target 目录下新建的wheels目录。官方提供的pyo3/maturinDocker 镜像基于 manylinux2014并把参数透传给maturin二进制docker run --rm -v $(pwd):/io ghcr.io/pyo3/maturin build --release # 或其他 maturin 参数该镜像非常精简只包含 python、maturin 和 stable Rust需要额外工具时可以在 manylinux 容器内自行执行命令。九、bindings 绑定类型maturin 支持多种绑定类型详见 bindings.md其中部分可以自动检测也可用-b/--bindings手动指定。自动检测逻辑在 src/bridge/detection.rs通过cargo metadata分析依赖图若存在pyo3/pyo3-ffi依赖则判定为 pyo3 绑定存在uniffi依赖判定为 uniffi存在 cdylib 目标但无 pyo3 依赖时判定为 cffi只有 bin 目标时判定为 bin。pyo3Rust 的 Python 绑定支持 CPython、PyPy 与 GraalPy。加入Cargo.toml依赖后 maturin 会自动检测。pyo3 绑定支持稳定 ABIPy_LIMITED_API/abi3/abi3t例如同时启用abi3-py310与abi3t-py315时一次构建只会选择一种稳定 ABI 家族想同时发布两种 wheel 需要分别构建如maturin build --interpreter python3.10与maturin build --interpreter python3.15tcffiwheel 兼容包括 PyPy 在内的所有 Python 版本。若 virtualenv 中未安装cffimaturin 会自动安装否则需自行pip install cffi。maturin 使用 cbindgen 生成头文件可通过项目根目录的cbindgen.toml定制也可用 build 脚本把头文件写到$PROJECT_ROOT/target/header.h。cffi 不会被自动检测除非项目中没有 pyo3 依赖bin把 Rust 二进制程序作为 Python 包分发二进制以 scripts 形式进入 wheel安装后出现在用户PATH如 virtualenv 的bin目录中。只有当项目只有 bin 目标、且无 pyo3 依赖或 cdylib 目标时才会自动检测。若同时发布二进制与库会让 wheel 体积翻倍官方建议在库中暴露 CLI 函数并用 Python 入口点包装uniffi使用 uniffi-rs 从接口定义文件生成 Pythonctypes绑定wheel 兼容包括 PyPy 在内的所有 Python 版本。十、配置[tool.maturin]关键选项maturin 的全部配置都在pyproject.toml的tool.maturin段完整说明见 config.md并与 CLI 参数一一对应配置解析与合并逻辑见 cargo_options.rs。常用键包括配置键说明module-name扩展模块的 Python 导入名支持my_package._native这类点分名称将 Rust 扩展安装为子模块python-sourcePython 源码目录默认srcpython-packages需要打包的 Python 包列表bindings绑定类型pyo3、pyo3-ffi、cffi、uniffi、bincompatibility控制平台标签与 PyPI 兼容性auditwheelauditwheel 模式repair、check、warn、skipinclude/exclude额外包含/排除的文件支持 glob可指定formatsdist/wheel还支持从build.rs的OUT_DIR引入生成文件strip是否剥离库以减小体积features激活的 Cargo features支持按 Python 版本条件化如{ feature pyo3/abi3-py311, python-version 3.11 }profile/editable-profileCargo 构建 profileeditable 构建可用editable-profile覆盖默认回退到profiledatawheel data 目录路径默认使用项目根目录的module-name.datatargets过滤要构建的 Cargo 编译目标注意区别于[tool.maturin.target.triple]pgo-commandPGO 性能剖析阶段执行的命令配合--pgouse-base-pythonPEP 517 构建时使用基础 Python 解释器而非 venv 解释器避免不必要的重编译[tool.maturin.sbom]SBOM 生成配置rust、auditwheel、include三键[tool.maturin.target.triple]目标架构专属选项目前仅 macOS 的macos-deployment-target[tool.maturin.generate-ci.github]maturin generate-ci的默认值pytest、zig、trusted-publishing 等十一、本地开发与导入钩子11.1maturin developmaturin develop默认以 debug 模式快速构建并安装到 virtualenv命令详解见 local_development.md。调试信息文件.pdb、.dSYM、.dwp默认随产物包含除非使用--strip。常用选项包括--release、--extras安装可选依赖、--skip-install仅原地构建扩展、--uv用 uv 替代 pip 安装等。maturin 自 v0.12.0 起支持 PEP 660 editable 安装pip install -e .或maturin develop均可。editable 模式下 Python 源码修改即时生效解释器直接在项目源码树中查找模块配合导入钩子后 Rust 源码修改也能自动触发重编译。11.2 maturin_import_hookmaturin_import_hook 提供在 Python 脚本导入 maturin 项目时自动重建的机制Rust 组件的修改像 Python 组件一样即时生效且消除了 Python 代码使用过期 Rust 组件的可能。安装与激活pip install maturin_import_hook python -m maturin_import_hook site installsite install会把它写入当前环境的sitecustomize.py每次解释器启动自动激活每个 virtualenv 只需执行一次site uninstall可移除。也可以在单个脚本顶部手动调用maturin_import_hook.install()。它只处理以 editable 方式maturin develop或pip install -e安装的 maturin 包还支持直接导入独立的.rs文件#[pymodule]名称必须与文件名一致并支持importlib.reload()、多项目并发构建、路径依赖变更检测等特性。生产环境可用MATURIN_IMPORT_HOOK_ENABLED0禁用构建缓存可用MATURIN_BUILD_DIR指定位置。十二、分发交叉编译、GitHub Actions 与 SBOM12.1 交叉编译maturin 对pyo3与bin绑定有较好的交叉编译支持见 distribution.mdLinux/macOS可使用 manylinux-cross Docker 镜像或自 v0.12.7 起使用zig cc链接maturin build --release --target aarch64-unknown-linux-gnu --zigWindowspyo3 0.16.5 的generate-import-lib特性可在无 Windows Python 库的情况下交叉编译扩展0.29.0 通过 raw-dylib 链接直接支持maturin 集成 cargo-xwin 自动下载 MSVC CRT 与 Windows SDK 头文件/导入库。12.2 GitHub Actionsmaturin generate-ci github可生成 GitHub Actions 工作流mkdir -p .github/workflows maturin generate-ci github .github/workflows/CI.yml发布到 PyPI 时默认使用 API token 认证在pyproject.toml中设置[tool.maturin.generate-ci.github] trusted-publishing true即可改用 PyPI 可信发布OIDC生成的工作流将执行uv publish --trusted-publishing always。12.3 SBOMmaturin 可以自动生成 CycloneDX SBOM 并放入 wheel 的.dist-info/sboms/目录遵循 PEP 770详见 sbom.mdRust 依赖树 SBOM通过 cargo-cyclonedx、auditwheel 修复时植入的共享库对应的系统包 SBOM、以及自定义 SBOM 文件。生成与禁用均通过[tool.maturin.sbom]配置--sbom-include命令行参数可在 CI 等场景追加文件。十三、Sphinx 文档集成与平台支持13.1 Sphinx / Read The Docs / Netlify为 Rust 扩展模块配置 Sphinx 文档会稍显复杂详见 sphinx.md。要点是确保pyproject.toml能构建 sdistpip install .可用并在.readthedocs.yaml中声明同时安装 Rust 工具链与 Pythonversion: 2 sphinx: builder: html build: os: ubuntu-20.04 tools: python: 3.9 rust: 1.55 python: install: - method: pip path: .混合项目切记不要在 Sphinx 的conf.py中把项目路径加入sys.path。Netlify 场景则需在.netlify.toml中配置构建命令并配套rust-toolchain、runtime.txt、requirements.txt文件。13.2 平台支持范围自动化测试GitHub Actions 上测试 Windows、macOS、Linux均 64 位 x86FreeBSD 通过 Cirrus CI 测试发布产物目标Windows 的 32/64 位 x86 与 arm64Linux 的 x86、x86_64、armv7、aarch64、ppc64lemusl与 s390xgnumacOS 的 x86_64 与 aarch64Python 支持CPython 3.8 至 3.14 经过 CI 测试PyPy 3.8 与 GraalPy 23.0 可用manylinux/musllinuxmanylinux2014及更新版本、musllinux_1_1及更新版本均受支持。十四、源码结构速览如果希望深入 maturin 内部实现可以从以下仓库路径入手src/main.rsCLI 入口与全部子命令定义src/build_options.rsBuildOptions按“Python/绑定选项 → 平台标签与 auditwheel → 输出产物 → Cargo 选项 → 压缩选项”分层组织构建配置src/cargo_options.rsCargoOptions及与pyproject.toml配置的合并逻辑src/bridge/detection.rs绑定类型自动检测、abi3/abi3t 稳定 ABI 推断src/pyproject_toml.rs[tool.maturin]配置的 TOML 模型maturin/init.pyPEP 517 后端实现test-crates/覆盖 pyo3、cffi、uniffi、bin 各类绑定与各种项目布局的测试示例工程。用户指南中的 迁移指南 记录了各版本间的破坏性变更如 0.13 起 sdist 不再默认构建、改用--sdist[package.metadata.maturin]迁移到[tool.maturin]等变更日志 提供完整变更明细贡献指南 说明了本地开发与测试流程运行cargo test需要virtualenv与wasm32-wasip1目标。结语从创建工程、本地开发、交叉编译到 manylinux 合规发布maturin 把 Rust/Python 混合项目的构建发布链路收敛到了极简配置之下。本文以用户指南为骨架梳理了全流程的关键操作与底层原理后续针对具体场景建议按需深入阅读 教程完整的 pyo3 猜数字游戏实战、配置、环境变量 与 发行 等专题章节。赞分享开发工具构建工具【免费下载链接】maturinBuild and publish crates with pyo3, cffi and uniffi bindings as well as rust binaries as python packages项目地址https://gitcode.com/gh_mirrors/ma/maturin点击查看免费下载相关推荐PyO3/maturin 项目安装指南全方位构建Python与Rust混合开发环境PyO3/maturin 项目安装指南全方位构建Python与Rust混合开发环境 前言 PyO3/maturin 是一个强大的工具链用于构建和发布包含Ru开发工具构建工具使用 Rye 开发 Rust Python 扩展模块maturin 构建流程与混合项目实战指南使用 Rye 开发 Rust Python 扩展模块maturin 构建流程与混合项目实战指南 Rye 官方推荐使用 maturin https://link开发工具CLImaturin 完整指南用 Rust 构建并发布 Python 包pyo3/cffi/uniffi 与二进制分发maturin 完整指南用 Rust 构建并发布 Python 包pyo3/cffi/uniffi 与二进制分发 导读 maturin前身 pyo3 p开发工具构建工具上一篇重塑AI编程范式Cline如何突破IDE工具的能力边界下一篇Touying让Typst幻灯片创作变得简单高效创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考