# setuptools-rust

> Setuptools Rust extension plugin

- **URL**: https://www.freshcrate.ai/projects/setuptools-rust
- **Author**: pypi
- **Category**: Frameworks
- **Latest version**: `1.12.1` (2026-04-21)
- **License**: Unknown
- **Source**: https://github.com/PyO3/setuptools-rust/blob/main/CHANGELOG.md
- **Homepage**: https://pypi.org/project/setuptools-rust/
- **Language**: Python
- **GitHub**: 672 stars, 108 forks
- **Registry**: pypi (`setuptools-rust`)
- **Tags**: `distutils`, `pypi`, `rust`, `setuptools`

## Description

# Setuptools plugin for Rust extensions

[![github actions](https://github.com/PyO3/setuptools-rust/actions/workflows/ci.yml/badge.svg)](https://github.com/PyO3/setuptools-rust/actions/workflows/ci.yml)
[![pypi package](https://badge.fury.io/py/setuptools-rust.svg)](https://pypi.org/project/setuptools-rust/)
[![readthedocs](https://readthedocs.org/projects/pip/badge/)](https://setuptools-rust.readthedocs.io/en/latest/)
[![Ruff](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json)](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

## Recent releases

| Version | Date | Urgency | Changes |
| --- | --- | --- | --- |
| `1.12.1` | 2026-04-21 | Low | Imported from PyPI (1.12.1) |
| `v1.12.1` | 2026-03-26 | Medium | ## What's Changed * Isolate `universal2` artifact-combination logic by @jakelishman in https://github.com/PyO3/setuptools-rust/pull/572 * Strip target suffix for cargo-zigbuild compatibility by @bet4it in https://github.com/PyO3/setuptools-rust/pull/534 * ci: configure trusted publishing by @davidhewitt in https://github.com/PyO3/setuptools-rust/pull/581  ## New Contributors * @jakelishman made their first contribution in https://github.com/PyO3/setuptools-rust/pull/572 * @bet4it made the |
| `v1.12.1` | 2026-03-26 | Medium | ## What's Changed * Isolate `universal2` artifact-combination logic by @jakelishman in https://github.com/PyO3/setuptools-rust/pull/572 * Strip target suffix for cargo-zigbuild compatibility by @bet4it in https://github.com/PyO3/setuptools-rust/pull/534 * ci: configure trusted publishing by @davidhewitt in https://github.com/PyO3/setuptools-rust/pull/581  ## New Contributors * @jakelishman made their first contribution in https://github.com/PyO3/setuptools-rust/pull/572 * @bet4it made the |
| `v1.12.1` | 2026-03-26 | Medium | ## What's Changed * Isolate `universal2` artifact-combination logic by @jakelishman in https://github.com/PyO3/setuptools-rust/pull/572 * Strip target suffix for cargo-zigbuild compatibility by @bet4it in https://github.com/PyO3/setuptools-rust/pull/534 * ci: configure trusted publishing by @davidhewitt in https://github.com/PyO3/setuptools-rust/pull/581  ## New Contributors * @jakelishman made their first contribution in https://github.com/PyO3/setuptools-rust/pull/572 * @bet4it made the |
| `v1.12.1` | 2026-03-26 | Low | ## What's Changed * Isolate `universal2` artifact-combination logic by @jakelishman in https://github.com/PyO3/setuptools-rust/pull/572 * Strip target suffix for cargo-zigbuild compatibility by @bet4it in https://github.com/PyO3/setuptools-rust/pull/534 * ci: configure trusted publishing by @davidhewitt in https://github.com/PyO3/setuptools-rust/pull/581  ## New Contributors * @jakelishman made their first contribution in https://github.com/PyO3/setuptools-rust/pull/572 * @bet4it made the |
| `v1.12.1` | 2026-03-26 | Low | ## What's Changed * Isolate `universal2` artifact-combination logic by @jakelishman in https://github.com/PyO3/setuptools-rust/pull/572 * Strip target suffix for cargo-zigbuild compatibility by @bet4it in https://github.com/PyO3/setuptools-rust/pull/534 * ci: configure trusted publishing by @davidhewitt in https://github.com/PyO3/setuptools-rust/pull/581  ## New Contributors * @jakelishman made their first contribution in https://github.com/PyO3/setuptools-rust/pull/572 * @bet4it made the |
| `v1.12.1` | 2026-03-26 | Low | ## What's Changed * Isolate `universal2` artifact-combination logic by @jakelishman in https://github.com/PyO3/setuptools-rust/pull/572 * Strip target suffix for cargo-zigbuild compatibility by @bet4it in https://github.com/PyO3/setuptools-rust/pull/534 * ci: configure trusted publishing by @davidhewitt in https://github.com/PyO3/setuptools-rust/pull/581  ## New Contributors * @jakelishman made their first contribution in https://github.com/PyO3/setuptools-rust/pull/572 * @bet4it made the |
| `v1.12.1` | 2026-03-26 | Low | ## What's Changed * Isolate `universal2` artifact-combination logic by @jakelishman in https://github.com/PyO3/setuptools-rust/pull/572 * Strip target suffix for cargo-zigbuild compatibility by @bet4it in https://github.com/PyO3/setuptools-rust/pull/534 * ci: configure trusted publishing by @davidhewitt in https://github.com/PyO3/setuptools-rust/pull/581  ## New Contributors * @jakelishman made their first contribution in https://github.com/PyO3/setuptools-rust/pull/572 * @bet4it made the |
| `v1.12.1` | 2026-03-26 | Low | ## What's Changed * Isolate `universal2` artifact-combination logic by @jakelishman in https://github.com/PyO3/setuptools-rust/pull/572 * Strip target suffix for cargo-zigbuild compatibility by @bet4it in https://github.com/PyO3/setuptools-rust/pull/534 * ci: configure trusted publishing by @davidhewitt in https://github.com/PyO3/setuptools-rust/pull/581  ## New Contributors * @jakelishman made their first contribution in https://github.com/PyO3/setuptools-rust/pull/572 * @bet4it made the |
| `v1.12.1` | 2026-03-26 | Low | ## What's Changed * Isolate `universal2` artifact-combination logic by @jakelishman in https://github.com/PyO3/setuptools-rust/pull/572 * Strip target suffix for cargo-zigbuild compatibility by @bet4it in https://github.com/PyO3/setuptools-rust/pull/534 * ci: configure trusted publishing by @davidhewitt in https://github.com/PyO3/setuptools-rust/pull/581  ## New Contributors * @jakelishman made their first contribution in https://github.com/PyO3/setuptools-rust/pull/572 * @bet4it made the |

## Citation

- HTML: https://www.freshcrate.ai/projects/setuptools-rust
- Markdown: https://www.freshcrate.ai/projects/setuptools-rust.md
- Dependencies JSON: https://www.freshcrate.ai/api/projects/setuptools-rust/deps

_Generated by freshcrate.ai. Indexes pypi releases for AI-agent ecosystem packages._