Features reference

PyO3 provides a number of Cargo features to customize functionality. This chapter of the guide provides detail on each of them.

By default, only the macros feature is enabled.

Features for extension module authors

`extension-module`

This feature is required when building a Python extension module using PyO3.

It tells PyO3's build script to skip linking against libpython.so on Unix platforms, where this must not be done.

See the building and distribution section for further detail.

`abi3`

This feature is used when building Python extension modules to create wheels which are compatible with multiple Python versions.

It restricts PyO3's API to a subset of the full Python API which is guaranteed by PEP 384 to be forwards-compatible with future Python versions.

See the building and distribution section for further detail.

The `abi3-pyXY` features

(abi3-py37, abi3-py38, abi3-py39, abi3-py310 and abi3-py311)

These features are extensions of the abi3 feature to specify the exact minimum Python version which the multiple-version-wheel will support.

See the building and distribution section for further detail.

`generate-import-lib`

This experimental feature is used to generate import libraries for Python DLL for MinGW-w64 and MSVC (cross-)compile targets.

Enabling it allows to (cross-)compile extension modules to any Windows targets without having to install the Windows Python distribution files for the target.

See the building and distribution section for further detail.

Features for embedding Python in Rust

`auto-initialize`

This feature changes Python::attach to automatically initialize a Python interpreter (by calling Python::initialize) if needed.

If you do not enable this feature, you should call Python::initialize() before attempting to call any other Python APIs.

Advanced Features

`experimental-async`

This feature adds support for async fn in #[pyfunction] and #[pymethods].

The feature has some unfinished refinements and performance improvements. To help finish this off, see issue #1632 and its associated draft PRs.

`experimental-inspect`

This feature adds to the built binaries introspection data that can be then retrieved using the pyo3-introspection crate to generate type stubs.

Also, this feature adds the pyo3::inspect module, as well as IntoPy::type_output and FromPyObject::type_input APIs to produce Python type "annotations" for Rust types.

This is a first step towards adding first-class support for generating type annotations automatically in PyO3, however work is needed to finish this off. All feedback and offers of help welcome on issue #2454.

`py-clone`

This feature was introduced to ease migration. It was found that delayed reference counting (which PyO3 used historically) could not be made sound and hence Clone-ing an instance of Py<T> is impossible when not attached to Python interpreter (it will panic). To avoid migrations introducing new panics without warning, the Clone implementation itself is now gated behind this feature.

`pyo3_disable_reference_pool`

This is a performance-oriented conditional compilation flag, e.g. set via $RUSTFLAGS, which disabled the global reference pool and the associated overhead for the crossing the Python-Rust boundary. However, if enabled, Dropping an instance of Py<T> when not attached to the Python interpreter will abort the process.

`macros`

This feature enables a dependency on the pyo3-macros crate, which provides the procedural macros portion of PyO3's API:

#[pymodule]
#[pyfunction]
#[pyclass]
#[pymethods]
#[derive(FromPyObject)]

It also provides the py_run! macro.

These macros require a number of dependencies which may not be needed by users who just need PyO3 for Python FFI. Disabling this feature enables faster builds for those users, as these dependencies will not be built if this feature is disabled.

This feature is enabled by default. To disable it, set default-features = false for the pyo3 entry in your Cargo.toml.

`multiple-pymethods`

This feature enables each #[pyclass] to have more than one #[pymethods] block.

Most users should only need a single #[pymethods] per #[pyclass]. In addition, not all platforms (e.g. Wasm) are supported by inventory, which is used in the implementation of the feature. For this reason this feature is not enabled by default, meaning fewer dependencies and faster compilation for the majority of users.

See the #[pyclass] implementation details for more information.

`nightly`

The nightly feature needs the nightly Rust compiler. This allows PyO3 to use the auto_traits and negative_impls features to fix the Python::detach function.

`resolve-config`

The resolve-config feature of the pyo3-build-config crate controls whether that crate's build script automatically resolves a Python interpreter / build configuration. This feature is primarily useful when building PyO3 itself. By default this feature is not enabled, meaning you can freely use pyo3-build-config as a standalone library to read or write PyO3 build configuration files or resolve metadata about a Python interpreter.

Optional Dependencies

These features enable conversions between Python types and types from other Rust crates, enabling easy access to the rest of the Rust ecosystem.

`anyhow`

Adds a dependency on anyhow. Enables a conversion from anyhow’s Error type to PyErr, for easy error handling.

`arc_lock`

Enables Pyo3's MutexExt trait for all Mutexes that extend on lock_api::Mutex or parking_lot::ReentrantMutex and are wrapped in an Arc type. Like Arc<parking_lot::Mutex>

`bigdecimal`

Adds a dependency on bigdecimal and enables conversions into its BigDecimal type.

`bytes`

Adds a dependency on bytes and enables conversions into its Bytes type.

`chrono`

Adds a dependency on chrono. Enables a conversion from chrono's types to python:

`chrono-local`

Enables conversion from and to Local timezones. The current system timezone as determined by iana_time_zone::get_timezone() will be used for conversions.

chrono::DateTime<Local> will convert from either of:

datetime objects with tzinfo equivalent to the current system timezone.
"naive" datetime objects (those without a tzinfo), as it is a convention that naive datetime objects should be treated as using the system timezone.

When converting to Python, Local tzinfo is converted to a zoneinfo.ZoneInfo matching the current system timezone.

NotNan -> PyFloat
OrderedFloat -> PyFloat

#[cfg(feature = "serde")]
#[allow(dead_code)]
mod serde_only {
use pyo3::prelude::*;
use serde::{Deserialize, Serialize};

#[pyclass]
#[derive(Serialize, Deserialize)]
struct Permission {
    name: String,
}

#[pyclass]
#[derive(Serialize, Deserialize)]
struct User {
    username: String,
    permissions: Vec<Py<Permission>>,
}
}

`smallvec`

Adds a dependency on smallvec and enables conversions into its SmallVec type.

`uuid`

Adds a dependency on uuid and enables conversions into its Uuid type.

Keyboard shortcuts

PyO3 user guide