PyO3/pyo3 · error

Cannot compile extensions for the free-threaded build on Pyt

Error message

Cannot compile extensions for the free-threaded build on Python versions earlier than 3.13, found {}.{}

What it means

Version guard raised while computing Windows link/library names from the resolved ABI: the configuration selects a free-threaded build but the interpreter version resolved to something earlier than 3.13. Free-threaded CPython (Py_GIL_DISABLED) does not exist before 3.13, so no such library can be linked.

Source

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

            "python{}{}_d",
            abi.version.major, abi.version.minor
        ))
    } else if abi.kind == PythonAbiKind::Stable(StableAbi::Abi3)
        || abi.kind == PythonAbiKind::Stable(StableAbi::Abi3t)
    {
        let mut lib_name = if debug {
            WINDOWS_STABLE_ABI_DEBUG_LIB_NAME.to_owned()
        } else {
            WINDOWS_STABLE_ABI_LIB_NAME.to_owned()
        };
        if abi.kind == PythonAbiKind::Stable(StableAbi::Abi3t) {
            lib_name = lib_name.replace("python3", "python3t");
        }
        Ok(lib_name)
    } else if abi.kind().is_free_threaded() {
        #[expect(deprecated, reason = "using constant internally")]
        {
            ensure!(abi.version() >= PythonVersion::PY313, "Cannot compile extensions for the free-threaded build on Python versions earlier than 3.13, found {}.{}", abi.version.major, abi.version.minor);
        }
        if debug {
            Ok(format!(
                "python{}{}t_d",
                abi.version.major, abi.version.minor
            ))
        } else {
            Ok(format!("python{}{}t", abi.version.major, abi.version.minor))
        }
    } else if debug {
        Ok(format!(
            "python{}{}_d",
            abi.version.major, abi.version.minor
        ))
    } else {
        Ok(format!("python{}{}", abi.version.major, abi.version.minor))
    }
}

View on GitHub (pinned to ac9b6899d3)

Solutions

1. Upgrade the target interpreter to 3.13+ when building free-threaded extensions
2. Drop the free-threaded ABI selection for older interpreters
3. Fix a wrong PYO3_CROSS_PYTHON_VERSION or sysconfigdata that misreports the version

When it happens

Trigger: Thrown at pyo3-build-config/src/impl_.rs:2438 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/47657584ea756f52. Report an issue: GitHub.