22 releases (6 breaking)

✓ Uses Rust 2018 edition

0.7.0-alpha.1 Apr 23, 2019
0.6.0 Mar 28, 2019
0.6.0-alpha.4 Feb 20, 2019
0.5.2 Nov 25, 2018
0.1.0 Jul 23, 2017

#10 in FFI

Download history 294/week @ 2019-01-08 370/week @ 2019-01-15 344/week @ 2019-01-22 310/week @ 2019-01-29 346/week @ 2019-02-05 553/week @ 2019-02-12 1065/week @ 2019-02-19 1213/week @ 2019-02-26 1655/week @ 2019-03-05 1295/week @ 2019-03-12 1040/week @ 2019-03-19 1634/week @ 2019-03-26 1428/week @ 2019-04-02 1204/week @ 2019-04-09 980/week @ 2019-04-16

4,356 downloads per month
Used in 18 crates (1 directly)




Build Status Build Status codecov crates.io Join the dev chat

Rust bindings for Python. This includes running and interacting with python code from a rust binaries as well as writing native python modules.

A comparison with rust-cpython can be found in the guide.


PyO3 supports Python 3.5 and up. The minimum required rust version is 1.34.0-nightly 2019-02-06.

PyPy is also supported (via cpyext) for Python 3.5 only, targeted PyPy version is 7.0.0. Please refer to the guide for installation instruction against PyPy.

You can either write a native Python module in rust or use Python from a Rust binary.

However, on some OSs, you need some additional packages. E.g. if you are on Ubuntu 18.04, please run

sudo apt install python3-dev python-dev

Using Rust from Python

PyO3 can be used to generate a native python module.


name = "string-sum"
version = "0.1.0"
edition = "2018"

name = "string_sum"
crate-type = ["cdylib"]

version = "0.7.0-alpha.1"
features = ["extension-module"]


// Not required when using Rust 2018
extern crate pyo3;

use pyo3::prelude::*;
use pyo3::wrap_pyfunction;

/// Formats the sum of two numbers as string
fn sum_as_string(a: usize, b: usize) -> PyResult<String> {
    Ok((a + b).to_string())

/// This module is a python module implemented in Rust.
fn string_sum(py: Python, m: &PyModule) -> PyResult<()> {


On Windows and Linux, you can build normally with cargo build --release. On MacOS, you need to set additional linker arguments. One option is to compile with cargo rustc --release -- -C link-arg=-undefined -C link-arg=dynamic_lookup, the other is to create a .cargo/config with the following content:

rustflags = [
  "-C", "link-arg=-undefined",
  "-C", "link-arg=dynamic_lookup",

For developing, you can copy and rename the shared library from the target folder: On MacOS, rename libstring_sum.dylib to string_sum.so, on Windows libstring_sum.dll to string_sum.pyd and on Linux libstring_sum.so to string_sum.so. Then open a Python shell in the same folder and you'll be able to import string_sum.

To build, test and publish your crate as Python module, you can use pyo3-pack or setuptools-rust. You can find an example for setuptools-rust in examples/word-count, while pyo3-pack should work on your crate without any configuration.

Using python from rust

Add pyo3 this to your Cargo.toml:

pyo3 = "0.7.0-alpha.1"

Example program displaying the value of sys.version:

// Not required when using Rust 2018
extern crate pyo3;

use pyo3::prelude::*;
use pyo3::types::IntoPyDict;

fn main() -> PyResult<()> {
    let gil = Python::acquire_gil();
    let py = gil.python();
    let sys = py.import("sys")?;
    let version: String = sys.get("version")?.extract()?;
    let locals = [("os", py.import("os")?)].into_py_dict(py);
    let code = "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);

Examples and tooling


PyO3 is licensed under the Apache-2.0 license. Python is licensed under the Python License.


~17K SLoC