Registry / devops / setuptools-rust

setuptools-rust

JSON →
library1.13.0pypypi✓ verified 25d ago

setuptools-rust is a setuptools extension plugin that simplifies the integration of Rust code compilation and packaging into Python projects, especially those leveraging PyO3. It handles the build process for Rust extensions, making it easier to distribute Python packages with native Rust components. The library is actively maintained, currently at version 1.12.1, with a regular release cadence to support new Python and Rust features.

pip install setuptools-rust
INSTALL
IMPORT
SIG · SETUPTOOLS-RUST
S
setuptools-rust
devopspythonv1.13.0
Install
1.8s avg
Import
837ms
Disk
20MB
Pass rate
10/ 10
Env Coverage10 / 10
glibc
3.93.13
musl
3.93.13
Install & Compatibility
Where this runs
tested against v1.13.0 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
musl
py 3.103.95 runs
installs and imports cleanly · install 0.0s · import 0.910s · 19.4MB
glibc
py 3.103.95 runs
installs and imports cleanly · install 1.8s · import 0.764s · 20MB
20MB installed
● package 20MB
Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

RustExtension
from setuptools_rust import RustExtension

This quickstart provides a `setup.py` example for building a Rust extension using `setuptools-rust`. It defines a `RustExtension` for `my_rust_package.my_module`, pointing to a `Cargo.toml`. Accompanying `pyproject.toml`, `Cargo.toml`, `my_rust_package/__init__.py`, and `src/lib.rs` file structures are commented within the code, demonstrating how to integrate a simple PyO3 Rust function into a Python package. After setting up these files, the project can be built and installed using `pip install .`.

from setuptools import setup from setuptools_rust import RustExtension setup( name='my_rust_package', version='0.1.0', rust_extensions=[ RustExtension( 'my_rust_package.my_module', './Cargo.toml', # debug=True, # Uncomment for debug builds # features=['some_feature'], # Optional Cargo features ) ], packages=['my_rust_package'], ) # To make this example runnable, ensure the following files exist: # # pyproject.toml: # [build-system] # requires = ["setuptools>=61.0.0", "setuptools-rust>=1.0.0", "wheel"] # build-backend = "setuptools.build_meta" # # Cargo.toml (at the project root, or specified path './Cargo.toml'): # [package] # name = "my_module" # version = "0.1.0" # edition = "2021" # # [lib] # name = "my_module" # crate-type = ["cdylib"] # # [dependencies] # pyo3 = { version = "0.21.2", features = ["extension-module"] } # # my_rust_package/__init__.py (empty or `from .my_module import *`): # # src/lib.rs (for the Rust extension): # use pyo3::prelude::*; # # #[pyfunction] # fn greet(name: &str) -> PyResult<String> { # Ok(format!("Hello, {} from Rust!", name)) # } # # #[pymodule] # fn my_module(_py: Python, m: &PyModule) -> PyResult<()> { # m.add_function(wrap_pyfunction!(greet, m)?)?; # Ok(()) # }
Debug
Known issues
breakingPython 3.8 support was dropped in setuptools-rust v1.11.0. Projects requiring 3.8 or older will fail to build with newer versions.
fix
Upgrade your Python environment to 3.9 or newer. If maintaining support for Python 3.8 is necessary, pin `setuptools-rust` to `<1.11.0`.
affects: >=1.11.0
deprecatedThe `py_limited_api` option for `RustExtension` was deprecated in v1.9.0. It's now recommended to let `setuptools-rust` automatically configure this based on `bdist_wheel` settings.
fix
Remove the `py_limited_api` option from your `RustExtension` definition. The build system will handle it automatically.
affects: >=1.9.0
gotchaThe Rust compiler (`rustc`) and Cargo build system must be installed and accessible in your system's PATH for `setuptools-rust` to function.
fix
Install Rust and Cargo, typically using `rustup install stable`, and ensure the installation directory (e.g., `~/.cargo/bin`) is added to your system's PATH. Verify with `cargo --version`.
affects: all
gotchaWhen building in a virtual environment, switching between environments might trigger unnecessary recompilations of Rust extensions.
fix
Set the environment variable `SETUPTOOLS_RUST_PEP517_USE_BASE_PYTHON=1` before building. This forces `setuptools-rust` to use the base interpreter path, reducing recompilations.
affects: >=1.10.0
gotchaEditable installs (`pip install -e .`) may default to release mode builds, making debugging more difficult.
fix
This was a regression in v1.10.0 and fixed in v1.10.1. Upgrade `setuptools-rust` to `1.10.1` or newer. Alternatively, explicitly set `debug=True` in your `RustExtension` configuration if using an affected version.
affects: 1.10.0
Errors
Common errors & fixes
command 'cargo' not found
The Rust toolchain, which includes the `cargo` build system, is not installed on the system or is not correctly configured in the system's PATH environment variable, which setuptools-rust relies on to build Rust extensions.
fix
Install the Rust toolchain using `rustup` by following the instructions on `rustup.rs`. Ensure that `~/.cargo/bin` (or its equivalent for your OS) is added to your system's PATH.
error: failed to run custom build command
The underlying Rust compilation process invoked by setuptools-rust through `cargo` failed. This is a generic error that wraps various Rust-specific issues, such as syntax errors in Rust code, missing Rust dependencies, or an incorrectly configured `Cargo.toml`.
fix
Examine the detailed output immediately following this error message to pinpoint the specific Rust compilation or `cargo` error. This typically involves fixing issues in your Rust code, ensuring all Rust dependencies are correctly specified in `Cargo.toml`, or addressing configuration problems within the Rust project.
ModuleNotFoundError: No module named 'setuptools_rust'
The `setuptools-rust` package itself is not installed in the Python environment where your `setup.py` (or `pyproject.toml`) script is being executed.
fix
Install the package using pip: `pip install setuptools-rust`. If using a `pyproject.toml` with build-system requirements, ensure `setuptools-rust` is listed in `build-system.requires`.
linker command failed with exit code 1
During the Rust build process, the Rust compiler successfully produced object files, but the system linker failed to combine them into the final shared library or executable, often due to missing system-level development tools or C/C++ compilers.
fix
Install essential build tools for your operating system: for Debian/Ubuntu, `sudo apt-get install build-essential`; for macOS, `xcode-select --install`; for Windows, install the 'Desktop development with C++' workload in Visual Studio Installer.
Upgrade
Version history
1.13.0latest on PyPI · released Jun 27, 2026
Audit
Dependencies

No dependency data recorded yet.

Agent activity
8 hits · last 30 days
node
6
Resources
setuptools-rust — pip install setuptools-rust · libregistry