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::with_gil
to automatically initialize a Python interpreter (by calling prepare_freethreaded_python
) if needed.
If you do not enable this feature, you should call pyo3::prepare_freethreaded_python()
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 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.
gil-refs
This feature is a backwards-compatibility feature to allow continued use of the "GIL Refs" APIs deprecated in PyO3 0.21. These APIs have performance drawbacks and soundness edge cases which the newer Bound<T>
smart pointer and accompanying APIs resolve.
This feature and the APIs it enables is expected to be removed in a future PyO3 version.
py-clone
This feature was introduced to ease migration. It was found that delayed reference counts cannot be made sound and hence Clon
ing an instance of Py<T>
must panic without the GIL being held. 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 assocaited overhead for the crossing the Python-Rust boundary. However, if enabled, Drop
ping an instance of Py<T>
without the GIL being held 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 thepyo3
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::allow_threads
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.
chrono
Adds a dependency on chrono. Enables a conversion from chrono's types to python:
- TimeDelta ->
PyDelta
- FixedOffset ->
PyDelta
- Utc ->
PyTzInfo
- NaiveDate ->
PyDate
- NaiveTime ->
PyTime
- DateTime ->
PyDateTime
chrono-tz
Adds a dependency on chrono-tz.
Enables conversion from and to Tz
.
It requires at least Python 3.9.
either
Adds a dependency on either. Enables a conversions into either’s Either
type.
eyre
Adds a dependency on eyre. Enables a conversion from eyre’s Report
type to PyErr
, for easy error handling.
hashbrown
Adds a dependency on hashbrown and enables conversions into its HashMap
and HashSet
types.
indexmap
Adds a dependency on indexmap and enables conversions into its IndexMap
type.
num-bigint
Adds a dependency on num-bigint and enables conversions into its BigInt
and BigUint
types.
num-complex
Adds a dependency on num-complex and enables conversions into its Complex
type.
num-rational
Adds a dependency on num-rational and enables conversions into its Ratio
type.
rust_decimal
Adds a dependency on rust_decimal and enables conversions into its Decimal
type.
serde
Enables (de)serialization of Py<T>
objects via serde.
This allows to use #[derive(Serialize, Deserialize)
on structs that hold references to #[pyclass]
instances
#[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.