PyO3/pyo3 · error

Cannot target free-threaded builds for Python versions befor

Error message

Cannot target free-threaded builds for Python versions before 3.13, tried to build for {}

What it means

Validation failure in PythonAbiBuilder::finalize: the requested configuration selects a free-threaded (Py_GIL_DISABLED) build, but the resolved target Python version is older than 3.13, the first CPython release with a free-threaded ABI. The combination is impossible, so finalize aborts ABI construction.

Source

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

    pub fn finalize(self) -> Result<PythonAbi> {
        // default to GIL-enabled version-specific ABI
        let kind = self.kind.unwrap_or(match self.implementation {
            PythonImplementation::RustPython => PythonAbiKind::Stable(StableAbi::Abi3t),
            _ => PythonAbiKind::VersionSpecific(GilUsed::GilEnabled),
        });
        if matches!(self.implementation, PythonImplementation::RustPython) {
            ensure!(matches!(kind, PythonAbiKind::Stable(StableAbi::Abi3t)),
                    "RustPython only supports targeting abi3t, it does not allow targeting other Python ABIs. Currently targeting '{kind}'")
        }
        if matches!(kind, PythonAbiKind::VersionSpecific(GilUsed::FreeThreaded))
            && self.version
                < (PythonVersion {
                    major: 3,
                    minor: 13,
                })
        {
            bail!(
                "Cannot target free-threaded builds for Python versions before 3.13, tried to build for {}", self.version
            )
        }
        Ok(PythonAbi {
            implementation: self.implementation,
            kind,
            version: self.version,
        })
    }
}

#[non_exhaustive]
#[derive(Copy, Clone, PartialEq, Eq)]
#[cfg_attr(test, derive(Debug))]
pub struct PythonAbi {
    implementation: PythonImplementation,
    kind: PythonAbiKind,
    version: PythonVersion,

View on GitHub (pinned to ac9b6899d3)

Solutions

1. Target Python 3.13 or newer when a free-threaded build is requested
2. Drop the free-threaded selection (do not enable Py_GIL_DISABLED / free-threaded ABI) for older interpreters
3. Set PYO3_CROSS_PYTHON_VERSION to an accurate version so the check sees the real interpreter version

When it happens

Trigger: Thrown at pyo3-build-config/src/impl_.rs:978 when the library encounters an invalid state.

Common situations: See trigger scenarios.

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