#single-file #python-module #pyo3 #generate #cargo

app cargo-single-pyo3

Generate a Python module from a single Rust file

4 releases

0.1.3 Feb 21, 2023
0.1.2 Jul 6, 2022
0.1.1 Oct 7, 2021
0.1.0 May 3, 2021

#291 in Cargo plugins

MIT license

167 lines

cargo-single-pyo3 crates.io

Utility to build Python modules from a single Rust files via pyo3. Inspired by cargo-single.


cargo install cargo-single-pyo3


First, create a single Rust file with a pyo3 module. Add any dependencies as double-slash comments at the top of the file. For example, if you create foo.rs with the contents:

// rand = "*"

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

fn sum_as_string(a: usize, b: usize) -> PyResult<String> {
  // using rand to demonstrate library support
  let c = rand::thread_rng().gen_range(0 ..= 1);
  Ok((a + b + c).to_string())

fn foo(py: Python, m: &PyModule) -> PyResult<()> {
  m.add_function(wrap_pyfunction!(sum_as_string, m)?)?;

Then run:

cargo single-pyo3 foo.rs

This should generate a file foo.so, which you can then import:

$ python3
>>> import foo
>>> foo.sum_as_string(1, 2)
>>> foo.sum_as_string(2, 2)

Usage notes

Module name: the name of the file is the name of the module, e.g. foo.rs generates foo.so. The name of the #[pymodule] function must be the same.

Build process: the tool creates a Cargo project in your temporary directory that is associated with the module name, e.g. /tmp/foo. This could cause any usual problems of conflicts between users or projects on the same machine, so be careful (or submit a PR if you have a different preference).

Pyo3 version: the Cargo dependency on pyo3 is automatically generated. If you need to change the version, use the --pyo3 flag, e.g. --pyo3 0.13. You can also use --pyo3 github to use the latest on main branch. As of 5/7/21, the github option was necessary to build on OS X.


~34K SLoC