{"id":1706,"library":"setuptools-rust","title":"setuptools-rust","description":"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.","status":"active","version":"1.12.1","language":"en","source_language":"en","source_url":"https://github.com/PyO3/setuptools-rust","tags":["build system","rust","setuptools","packaging","pyo3","extension"],"install":[{"cmd":"pip install setuptools-rust","lang":"bash","label":"Install stable version"}],"dependencies":[],"imports":[{"symbol":"RustExtension","correct":"from setuptools_rust import RustExtension"}],"quickstart":{"code":"from setuptools import setup\nfrom setuptools_rust import RustExtension\n\nsetup(\n    name='my_rust_package',\n    version='0.1.0',\n    rust_extensions=[\n        RustExtension(\n            'my_rust_package.my_module',\n            './Cargo.toml',\n            # debug=True, # Uncomment for debug builds\n            # features=['some_feature'], # Optional Cargo features\n        )\n    ],\n    packages=['my_rust_package'],\n)\n\n# To make this example runnable, ensure the following files exist:\n#\n# pyproject.toml:\n# [build-system]\n# requires = [\"setuptools>=61.0.0\", \"setuptools-rust>=1.0.0\", \"wheel\"]\n# build-backend = \"setuptools.build_meta\"\n#\n# Cargo.toml (at the project root, or specified path './Cargo.toml'):\n# [package]\n# name = \"my_module\"\n# version = \"0.1.0\"\n# edition = \"2021\"\n#\n# [lib]\n# name = \"my_module\"\n# crate-type = [\"cdylib\"]\n#\n# [dependencies]\n# pyo3 = { version = \"0.21.2\", features = [\"extension-module\"] }\n#\n# my_rust_package/__init__.py (empty or `from .my_module import *`):\n#\n# src/lib.rs (for the Rust extension):\n# use pyo3::prelude::*;\n#\n# #[pyfunction]\n# fn greet(name: &str) -> PyResult<String> {\n#     Ok(format!(\"Hello, {} from Rust!\", name))\n# }\n#\n# #[pymodule]\n# fn my_module(_py: Python, m: &PyModule) -> PyResult<()> {\n#     m.add_function(wrap_pyfunction!(greet, m)?)?;\n#     Ok(())\n# }","lang":"python","description":"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 .`."},"warnings":[{"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`.","message":"Python 3.8 support was dropped in setuptools-rust v1.11.0. Projects requiring 3.8 or older will fail to build with newer versions.","severity":"breaking","affected_versions":">=1.11.0"},{"fix":"Remove the `py_limited_api` option from your `RustExtension` definition. The build system will handle it automatically.","message":"The `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.","severity":"deprecated","affected_versions":">=1.9.0"},{"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`.","message":"The Rust compiler (`rustc`) and Cargo build system must be installed and accessible in your system's PATH for `setuptools-rust` to function.","severity":"gotcha","affected_versions":"all"},{"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.","message":"When building in a virtual environment, switching between environments might trigger unnecessary recompilations of Rust extensions.","severity":"gotcha","affected_versions":">=1.10.0"},{"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.","message":"Editable installs (`pip install -e .`) may default to release mode builds, making debugging more difficult.","severity":"gotcha","affected_versions":"1.10.0"}],"env_vars":null,"last_verified":"2026-04-09T00:00:00.000Z","next_check":"2026-07-08T00:00:00.000Z"}