Description

# Setuptools plugin for Rust extensions [](https://github.com/PyO3/setuptools-rust/actions/workflows/ci.yml) [](https://pypi.org/project/setuptools-rust/) [](https://setuptools-rust.readthedocs.io/en/latest/) [](https://github.com/astral-sh/ruff) `setuptools-rust` is a plugin for `setuptools` to build Rust Python extensions implemented with [PyO3](https://github.com/PyO3/pyo3) or [rust-cpython](https://github.com/dgrunwald/rust-cpython). Compile and distribute Python extensions written in Rust as easily as if they were written in C. ## Quickstart The following is a very basic tutorial that shows how to use `setuptools-rust` in `pyproject.toml`. It assumes that you already have a bunch of Python and Rust files that you want to distribute. You can see examples for these files in the [`examples/hello-world`](https://github.com/PyO3/setuptools-rust/tree/main/examples/hello-world) directory in the [github repository](https://github.com/PyO3/setuptools-rust). The [PyO3 docs](https://pyo3.rs) have detailed information on how to write Python modules in Rust. ``` hello-world ├── python │ └── hello_world │ └── __init__.py └── rust └── lib.rs ``` Once the implementation files are in place, we need to add a `pyproject.toml` file that tells anyone that wants to use your project how to build it. In this file, we use an [array of tables](https://toml.io/en/v1.0.0#array-of-tables) (TOML jargon equivalent to Python's list of dicts) for ``[[tool.setuptools-rust.ext-modules]]``, to specify different extension modules written in Rust: ```toml # pyproject.toml [build-system] requires = ["setuptools", "setuptools-rust"] build-backend = "setuptools.build_meta" [project] name = "hello-world" version = "1.0" [tool.setuptools.packages] # Pure Python packages/modules find = { where = ["python"] } [[tool.setuptools-rust.ext-modules]] # Private Rust extension module to be nested into the Python package target = "hello_world._lib" # The last part of the name (e.g. "_lib") has to match lib.name in Cargo.toml, # but you can add a prefix to nest it inside of a Python package. path = "Cargo.toml" # Default value, can be omitted binding = "PyO3" # Default value, can be omitted ``` Each extension module should map directly into the corresponding `[lib]` table on the [Cargo manifest file](https://doc.rust-lang.org/cargo/reference/manifest.html): ```toml # Cargo.toml [package] name = "hello-world" version = "0.1.0" edition = "2021" [dependencies] pyo3 = "0.25" [lib] name = "_lib" # private module to be nested into Python package, # needs to match the name of the function with the `[#pymodule]` attribute path = "rust/lib.rs" crate-type = ["cdylib"] # required for shared library for Python to import from. # See more keys and their definitions at https://doc.rust-lang.org/cargo/reference/manifest.html # See also PyO3 docs on writing Cargo.toml files at https://pyo3.rs ``` You will also need to tell Setuptools that the Rust files are required to build your project from the [source distribution](https://setuptools.pypa.io/en/latest/userguide/miscellaneous.html). That can be done either via `MANIFEST.in` (see example below) or via a plugin like [`setuptools-scm`](https://pypi.org/project/setuptools-scm/). ``` # MANIFEST.in include Cargo.toml recursive-include rust *.rs ``` With these files in place, you can install the project in a virtual environment for testing and making sure everything is working correctly: ```powershell # cd hello-world python3 -m venv .venv source .venv/bin/activate # on Linux or macOS .venv\Scripts\activate # on Windows python -m pip install -e . python >>> import hello_world # ... try running something from your new extension module ... # ... better write some tests with pytest ... ``` ## Environment variables for configuration As well as all [environment variables supported by Cargo](https://doc.rust-lang.org/cargo/reference/environment-variables.html#environment-variables-cargo-reads), `setuptools-rust` also supports the following: - `SETUPTOOLS_RUST_CARGO_PROFILE`: used to override the profile of the Rust build. Defaults to `release`, e.g. set to `dev` to do a debug build. ## Next steps and final remarks - When you are ready to distribute your project, have a look on [the notes in the documentation about building wheels](https://setuptools-rust.readthedocs.io/en/latest/building_wheels.html). - Cross-compiling is also supported, using one of [`crossenv`](https://github.com/benfogle/crossenv), [`cross`](https://github.com/rust-embedded/cross) or [`cargo-zigbuild`](https://github.com/messen