PyO3 Maturin 完整安装与使用手册一、基础项目信息1.1 PyO3 核心信息表格项目内容GitHub 地址https://github.com/PyO3/pyo3官方文档https://pyo3.rs开源协议MIT / Apache-2.0 双协议支持免费商用稳定版本0.23.xPython 支持Python 3.8兼容 CPython、PyPy、GraalPy配套构建工具maturin官方推荐1.2 Maturin 核心信息maturin 为 PyO3 配套构建工具用于将 Rust 代码编译为 Python 可直接安装的.whl包表格项目内容GitHub 地址https://github.com/PyO3/maturin官方文档https://www.maturin.rs最新版本1.12.22026 年 3 月发布开源协议Apache-2.0 / MIT 双协议二、前置环境安装2.1 安装 Rust 工具链bash运行# 一键安装 rustup、rustc、cargo curl --proto https --tlsv1.2 -sSf https://sh.rustup.rs | sh安装完成后重启终端验证安装bash运行rustc --version cargo --version2.2 安装 maturin三选一uv 方案推荐bash运行# 方案1uv 安装推荐适配 uv 项目工作流 uv tool install maturin # 方案2pipx 安装 pipx install maturin # 方案3原生 pip 安装 pip install maturin验证 maturin 是否生效bash运行maturin --version三、完整项目开发流程3.1 创建 PyO3 混合项目bash运行# 新建项目 my_fast_tool maturin new my_fast_tool cd my_fast_tool自动生成目录结构plaintextmy_fast_tool/ ├── Cargo.toml # Rust 依赖配置 ├── pyproject.toml # Python 打包规范配置 └── src/ └── lib.rs # Rust 核心代码Python 导出逻辑3.2 编写 Rust 导出代码src/lib.rsrust运行use pyo3::prelude::*; // 标记函数可暴露至 Python #[pyfunction] fn fast_calculate(numbers: Veci64) - i64 { numbers.iter().sum() } // 模块入口注册所有导出函数 #[pymodule] fn my_fast_tool(m: Bound_, PyModule) - PyResult() { m.add_function(wrap_pyfunction!(fast_calculate, m)?)?; Ok(()) }3.3 编译项目两种模式模式 1开发调试热加载推荐日常迭代编译后自动安装至当前虚拟环境修改代码无需手动重装bash运行maturin develop模式 2生产打包生成 whl 安装包bash运行maturin build --release产物输出目录target/wheels/3.4 使用 uv 安装编译后的 whl 包bash运行# 写入项目依赖更新 pyproject.toml uv add ./target/wheels/my_fast_tool-0.1.0-cp312-cp312-linux_x86_64.whl # 仅安装至虚拟环境不修改项目配置 uv pip install ./target/wheels/my_fast_tool-0.1.0-cp312-cp312-linux_x86_64.whl3.5 Python 调用 Rust 代码python运行import my_fast_tool res my_fast_tool.fast_calculate([1, 2, 3, 4, 5]) print(res) # 输出 15四、发布至 PyPI可选方式 1maturin 一键发布bash运行maturin publish方式 2maturin 打包 uv 发布bash运行# 先构建 release 包 maturin build --release # 使用 uv 上传至 PyPI uv publish五、整体流程总结plaintext安装 Rust maturin ↓ maturin new 创建混合项目 ↓ 编写 src/lib.rs Rust 业务代码 ↓ maturin develop 本地调试 或 maturin build --release 生成 whl 包 ↓ uv add / uv pip install 安装编译包 ↓ Python import 直接调用 Rust 高性能函数
