+2
Daily
16,328
stars
1,054
forks
99
watchers
4,184
prs
1,797
issues
110
releases
README
PyO3
Rust bindings for Python, including tools for creating native Python extension modules. Running and interacting with Python code from a Rust binary is also supported.
- User Guide: stable | main
- API Documentation: stable | main
Usage
Requires Rust 1.85 or greater.
PyO3 supports the following Python distributions:
- CPython 3.9 or greater
- PyPy 7.3 (Python 3.11+)
- GraalPy 25.4 or greater (Python 3.13+)
You can use PyO3 to write a native Python module in Rust, or to embed Python in a Rust binary. The following sections explain each of these in turn.
Using Rust from Python
PyO3 can be used to generate a native Python module. The easiest way to try this out for the first time is to use maturin. maturin is a tool for building and publishing Rust-based Python packages with minimal configuration. The following steps install maturin, use it to generate and build a new Python package, and then launch Python to import and execute a function from the package.
First, follow the commands below to create a new directory containing a new Python virtualenv, and install maturin into the virtualenv using Python's package manager, pip:
bash
(replace string_sum with the desired package name)
$ mkdir string_sum
$ cd string_sum
$ python -m venv .env
$ source .env/bin/activate
$ pip install maturin
Still inside this string_sum directory, now run maturin init. This will generate the new package source. When given the choice of bindings to use, select pyo3 bindings:
bash
$ maturin init
✔ 🤷 What kind of bindings to use? · pyo3
✨ Done! New project created string_sum
The most important files generated by this command are Cargo.toml and lib.rs, which will look roughly like the following:
Cargo.toml
toml
[package]
name = "string_sum"
version = "0.1.0"
edition = "2024"
[lib]
The name of the native library. This is the name which will be used in Python to import the
library (i.e. import string_sum). If you change this, you must also change the name of the
[pymodule] in src/lib.rs.
name = "string_sum"
"cdylib" is necessary to produce a shared library for Python to import from.
Downstream Rust code (including code in bin/, examples/, and tests/) will not be able
to use string_sum; unless the "rlib" or "lib" crate type is also included, e.g.:
crate-type = ["cdylib", "rlib"]
crate-type = ["cdylib"]
[dependencies]
pyo3 = "0.30.0"
src/lib.rs
rust
/// A Python module implemented in Rust. The name of this module must match
/// the lib.name setting in the Cargo.toml, else Python will not be able to
/// import the module.
[pyo3::pymodule]
mod string_sum {
use pyo3::prelude::;
/// Formats the sum of two numbers as string.
[pyfunction]
fn sum_as_string(a: usize, b: usize) - PyResult {
Ok((a + b).to_string())
}
}
Finally, run maturin develop. This will build the package and install it into the Python virtualenv previously created and activated. The package is then ready to be used from python:
bash
$ maturin develoTop issues
#2454Python Interface (.pyi) generation and runtime inspection70 comments · 2022-06-15#417Support exporting Rust enums to Python (full ADTs)58 comments · 2019-03-24#1632`async fn` tracking issue53 comments · 2021-05-25#576Support sub-interpreters48 comments · 2019-08-14#1444Sharing pyclasses between multiple Rust packages47 comments · 2021-02-24#3640`Python::allow_threads` is unsound in the presence of `scoped-tls`.43 comments · 2023-12-11#3900Declarative modules next steps33 comments · 2024-02-26#1085Iterator examples without `Clone`33 comments · 2020-08-06
Discussions
#6558RustScenic: gene-network inference with PyO3, NumPy views and Rayon0 comments · 2026-10-26#6495Seam: step from Python into PyO3 Rust code in VS Code0 comments · 2026-10-10#6317Stoping a python task from rust code1 comments · 2026-08-11#6290Py why does not have a lifetime?4 comments · 2026-08-04#6170Please reconsider the Python support policy2 comments · 2026-06-30#6136Implement #[pyclass(generic)] for (complex) enums1 comments · 2026-06-15#6082Docs about writing Rust tests that indirectly call Python with `::attach()`?3 comments · 2026-05-29#6079Failed to import scipy with pyo31 comments · 2026-05-28
Latest release
PyO3 0.30.1 v0.30.1 2026-10-14PyO3 0.30.1 is a re-release of PyO3 0.30.0 after investments in CI security unfortunately led to a failed crates.io publish. Rather than delete the failed tag, this new tag comes after the CI issues have (hopefully) been corrected. Thanks to @davidhewitt @Tpt and @viicos for the investigation and fixes.