PyO3/pyo3 · error

Cannot target an abi3t version below {MINIMUM_SUPPORTED_VERS

Error message

Cannot target an abi3t version below {MINIMUM_SUPPORTED_VERSION_ABI3T}

What it means

When targeting the free-threaded stable ABI (abi3t), pyo3 enforces a minimum supported Python version constant MINIMUM_SUPPORTED_VERSION_ABI3T. Requesting an abi3t target older than that floor is unsupported because the free-threaded stable ABI did not exist or was not stable before that release, so the build script bails.

Source

Thrown at pyo3-build-config/src/impl_.rs:2334

/// Must be called from a PyO3 crate build script.
fn default_stable_abi_config(
    host: &Triple,
    abi3_version: Option<PythonVersion>,
    abi3t_version: Option<PythonVersion>,
) -> Result<InterpreterConfig> {
    if abi3_version.is_none() && abi3t_version.is_none() {
        bail!("Neither abi3 or abi3t features are enabled")
    }
    let (stable_abi, version) = if let Some(version) = abi3_version {
        (StableAbi::Abi3, version)
    } else if let Some(version) = abi3t_version {
        (StableAbi::Abi3t, version)
    } else {
        unreachable!();
    };

    if stable_abi == StableAbi::Abi3t && version < MINIMUM_SUPPORTED_VERSION_ABI3T {
        bail!("Cannot target an abi3t version below {MINIMUM_SUPPORTED_VERSION_ABI3T}")
    }

    // FIXME: PyPy & GraalPy do not support the Stable ABI.
    let target_abi = PythonAbiBuilder::new(PythonImplementation::CPython, version)
        .stable_abi(stable_abi)
        .finalize()?;
    let builder = InterpreterConfigBuilder::new(PythonImplementation::CPython, version)
        .target_abi(target_abi);
    if host.operating_system == OperatingSystem::Windows {
        builder.lib_name(default_lib_name_windows(target_abi, false, false)?)
    } else {
        builder
    }
    .finalize()
}

/// Detects the cross compilation target interpreter configuration from all
/// available sources (PyO3 environment variables, Python sysconfigdata, etc.).

View on GitHub (pinned to ac9b6899d3)

Solutions

1. Raise the abi3t target version to at least MINIMUM_SUPPORTED_VERSION_ABI3T (currently the 3.13 free-threaded ABI)
2. If you need to support older Pythons, use plain `abi3` instead of `abi3t`
3. Check the pyo3 docs/changelog for the exact minimum free-threaded version supported by your pyo3 release

Example fix

// before
pyo3 = { version = "0.23", features = ["extension-module", "abi3-py39"] }  # too old for abi3t
// after
pyo3 = { version = "0.23", features = ["extension-module"] }  # target free-threaded CPython 3.13t+ only

// shell
PYO3_PYTHON="${PYO3_PYTHON:-python3}"; VER=$($PYO3_PYTHON -c 'import sys; print(sys.version_info[:2])'); echo "target=$VER — abi3t requires free-threaded CPython 3.13+"

When it happens

Trigger: Setting an abi3t minimum version (via feature/env/config such as an abi3t-py3XY-style selection or PYO3 config) whose PythonVersion compares less than MINIMUM_SUPPORTED_VERSION_ABI3T (the oldest free-threaded CPython pyo3 supports).

Common situations: Developers experimentally request abi3t with an older interpreter version pinned (e.g. py3.9) not realizing free-threading only exists from CPython 3.13; CI matrices pin old Python versions while the free-threaded feature is enabled.

Related errors

• Neither abi3 or abi3t features are enabled
• cannot set a minimum Python version {} higher than the inter
• At least GraalPy version {} needed, got {}
• Invalid config that sets both target_abi and abi3.
• failed to run the Python interpreter at {}: {}

AI-assisted analysis of PyO3/pyo3@ac9b6899d3 (2026-09-05). Data as JSON: /api/errors/b1dea3b987c35b66. Report an issue: GitHub.