Repository files navigation

Rust bindings forPython, 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

Requires Rust 1.83 or greater.

PyO3 supports the following Python distributions:

• CPython 3.7 or greater
• PyPy 7.3 (Python 3.11+)
• GraalPy 25.0 or greater (Python 3.12+)

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.

PyO3 can be used to generate a native Python module. The easiest way to try this out for the first time is to usematurin.maturin is a tool for building and publishing Rust-based Python packages with minimal configuration. The following steps installmaturin, 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 Pythonvirtualenv, and installmaturin into the virtualenv using Python's package manager,pip:

# (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 thisstring_sum directory, now runmaturin init. This will generate the new package source. When given the choice of bindings to use, select pyo3 bindings:

$ maturin init✔ 🤷 What kind of bindings to use? · pyo3  ✨ Done! New project created string_sum

The most important files generated by this command areCargo.toml andlib.rs, which will look roughly like the following:

Cargo.toml

[package]name ="string_sum"version ="0.1.0"edition ="2021"[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.28.2"

src/lib.rs

/// 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]fnsum_as_string(a:usize,b:usize) ->PyResult<String>{Ok((a + b).to_string())}}

Finally, runmaturin 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 frompython:

$ maturin develop# lots of progress output as maturin runs the compilation...$ python>>> import string_sum>>> string_sum.sum_as_string(5, 20)'25'

To make changes to the package, just edit the Rust source code and then re-runmaturin develop to recompile.

To run this all as a single copy-and-paste, use the bash script below (replacestring_sum in the first command with the desired package name):

mkdir string_sum&&cd"$_"python -m venv .envsource .env/bin/activatepip install maturinmaturin init --bindings pyo3maturin develop

If you want to be able to runcargo test or use this project in a Cargo workspace and are running into linker issues, there are some workarounds inthe FAQ.

As well as withmaturin, it is possible to build usingsetuptools-rust ormanually. Both offer more flexibility thanmaturin but require more configuration to get started.

To embed Python into a Rust binary, you need to ensure that your Python installation contains a shared library. The following steps demonstrate how to ensure this (for Ubuntu), and then give some example code which runs an embedded Python interpreter.

To install the Python shared library on Ubuntu:

sudo apt install python3-dev

To install the Python shared library on RPM based distributions (e.g. Fedora, Red Hat, SuSE), install thepython3-devel package.

Start a new project withcargo new and addpyo3 to theCargo.toml like this:

[dependencies.pyo3]version ="0.28.2"# Enabling this cargo feature will cause PyO3 to start a Python interpreter on first call to `Python::attach`features = ["auto-initialize"]

Example program displaying the value ofsys.version and the current user name:

use pyo3::prelude::*;use pyo3::types::IntoPyDict;fnmain() ->PyResult<()>{Python::attach(|py|{let sys = py.import("sys")?;let version:String = sys.getattr("version")?.extract()?;let locals =[("os", py.import("os")?)].into_py_dict(py)?;let code =c"os.getenv('USER') or os.getenv('USERNAME') or 'Unknown'";let user:String = py.eval(code,None,Some(&locals))?.extract()?;println!("Hello {}, I'm Python {}", user, version);Ok(())})}

The guide hasa section with lots of examplesabout this topic.

• maturinBuild and publish crates with pyo3, rust-cpython or cffi bindings as well as rust binaries as python packages
• setuptools-rustSetuptools plugin for Rust support.
• pyo3-builtSimple macro to expose metadata obtained with thebuilt crate as aPyDict
• rust-numpyRust binding of NumPy C-API
• dict-deriveDerive FromPyObject to automatically transform Python dicts into Rust structs
• pyo3-logBridge from Rust to Python logging
• pythonizeSerde serializer for converting Rust objects to JSON-compatible Python objects
• pyo3-async-runtimesUtilities for interoperability with Python's Asyncio library and Rust's async runtimes.
• rustimportDirectly import Rust files or crates from Python, without manual compilation step. Provides pyo3 integration by default and generates pyo3 binding code automatically.
• pyo3-arrowLightweightApache Arrow integration for pyo3.
• pyo3-bytesIntegration betweenbytes and pyo3.
• pyo3-object_storeIntegration betweenobject_store andpyo3.

• aniseA modern, high-performance toolkit for spacecraft mission design, notably used to help softly land Firefly Blue Ghost on the Moon on 02 Feb 2025.
• arro3A minimal Python library for Apache Arrow, connecting to the Rust arrow crate.
  • arro3-computearro3-compute
  • arro3-corearro3-core
  • arro3-ioarro3-io
• bed-readerRead and write the PLINK BED format, simply and efficiently.
  • Shows Rayon/ndarray::parallel (including capturing errors, controlling thread num), Python types to Rust generics, Github Actions
• blake3-pyPython bindings for theBLAKE3 cryptographic hash function.
  • Parallelizedbuilds on GitHub Actions for MacOS, Linux, Windows, including free-threaded 3.13t wheels.
• cellular_razaA cellular agent-based simulation framework for building complex models from a clean slate.
• connector-xFastest library to load data from DB to DataFrames in Rust and Python.
• cryptographyPython cryptography library with some functionality in Rust.
• css-inlineCSS inlining for Python implemented in Rust.
• datafusion-pythonA Python library that binds to Apache Arrow in-memory query engine DataFusion.
• deltalake-pythonNative Delta Lake Python binding based on delta-rs with Pandas integration.
• fastbloomA fastbloom filter |counting bloom filter implemented by Rust for Rust and Python!
• fastuuidPython bindings to Rust's UUID library.
• fast-pasetoHigh-performance PASETO (Platform-Agnostic Security Tokens) implementation with Python bindings.
• feosLightning fast thermodynamic modeling in Rust with fully developed Python interface.
• finalyticsInvestment Analysis library in Rust | Python.
• forustA lightweight gradient boosted decision tree library written in Rust.
• geo-indexA Rust crate andPython library for packed, immutable, zero-copy spatial indexes.
• granianA Rust HTTP server for Python applications.
• haemA Python library for working on Bioinformatics problems.
• hifitimeA high fidelity time management library for engineering and scientific applications where general relativity and time dilation matter.
• html2text-rsPython library for converting HTML to markup or plain text.
• html-py-everUsinghtml5ever throughkuchiki to speed up html parsing and css-selecting.
• hudi-rsThe native Rust implementation for Apache Hudi, with C++ & Python API bindings.
• inline-pythonInline Python code directly in your Rust code.
• johnnycanencrypt OpenPGP library with Yubikey support.
• jsonschemaA high-performance JSON Schema validator for Python.
• mocpyAstronomical Python library offering data structures for describing any arbitrary coverage regions on the unit sphere.
• obstoreThe simplest, highest-throughput Python interface to Amazon S3, Google Cloud Storage, Azure Storage, & other S3-compliant APIs, powered by Rust.
• opendalA data access layer that allows users to easily and efficiently retrieve data from various storage services in a unified way.
• orjsonFast Python JSON library.
• ormsgpackFast Python msgpack library.
• polarsFast multi-threaded DataFrame library in Rust | Python | Node.js.
• pycrdtPython bindings for the Rust CRDT implementationYrs.
• pydantic-coreCore validation logic for pydantic written in Rust.
• primpThe fastest python HTTP client that can impersonate web browsers by mimicking their headers and TLS/JA3/JA4/HTTP2 fingerprints.
• radiate:A high-performance evolution engine for genetic programming and evolutionary algorithms.
• rateslibA fixed income library for Python using Rust extensions.
• riverOnline machine learning in python, the computationally heavy statistics algorithms are implemented in Rust.
• robyn A Super Fast Async Python Web Framework with a Rust runtime.
• rust-python-coverageExample PyO3 project with automated test coverage for Rust and Python.
• rnet Asynchronous Python HTTP Client with Black Magic
• sailUnifying stream, batch, and AI workloads with Apache Spark compatibility.
• tiktokenA fast BPE tokeniser for use with OpenAI's models.
• tokenizersPython bindings to the Hugging Face tokenizers (NLP) written in Rust.
• tzfpyA fast package to convert longitude/latitude to timezone name.
• toml-rsA High-Performance TOML v1.0.0 and v1.1.0 parser for Python written in Rust.
• utilesFast Python web-map tile utilities

• (Video) Using Rust in Free-Threaded vs Regular Python 3.13 - Jun 4, 2025
• (Video) Techniques learned from five years finding the way for Rust in Python - Feb 26, 2025
• (Podcast) Bridging Python and Rust: An Interview with PyO3 Maintainer David Hewitt - Aug 30, 2024
• (Video) PyO3: From Python to Rust and Back Again - Jul 3, 2024
• Parsing Python ASTs 20x Faster with Rust - Jun 17, 2024
• (Video) How Python Harnesses Rust through PyO3 - May 18, 2024
• (Video) Combining Rust and Python: The Best of Both Worlds? - Mar 1, 2024
• (Video) Extending Python with Rust using PyO3 - Dec 16, 2023
• A Week of PyO3 + rust-numpy (How to Speed Up Your Data Pipeline X Times) - Jun 6, 2023
• (Podcast) PyO3 with David Hewitt - May 19, 2023
• Making Python 100x faster with less than 100 lines of Rust - Mar 28, 2023
• How Pydantic V2 leverages Rust's Superpowers - Feb 4, 2023
• How we extended the River stats module with Rust using PyO3 - Dec 23, 2022
• Nine Rules for Writing Python Extensions in Rust - Dec 31, 2021
• Calling Rust from Python using PyO3 - Nov 18, 2021
• davidhewitt's 2021 talk at Rust Manchester meetup - Aug 19, 2021
• Incrementally porting a small Python project to Rust - Apr 29, 2021
• Vortexa - Integrating Rust into Python - Apr 12, 2021
• Writing and publishing a Python module in Rust - Aug 2, 2020

Everyone is welcomed to contribute to PyO3! There are many ways to support the project, such as:

• help PyO3 users with issues on GitHub andDiscord
• improve documentation
• write features and bugfixes
• publish blogs and examples of how to use PyO3

Ourcontributing notes andarchitecture guide have more resources if you wish to volunteer time for PyO3 and are searching where to start.

If you don't have time to contribute yourself but still wish to support the project's future success, some of our maintainers have GitHub sponsorship pages:

• davidhewitt
• messense

PyO3 is licensed under theApache-2.0 license or theMIT license, at your option.

Python is licensed under thePython License.

Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in PyO3 by you, as defined in the Apache License, shall be dual-licensed as above, without any additional terms or conditions.