PyO3/pyo3 · error

PyO3 does not support the free-threaded build of CPython ver

Error message

PyO3 does not support the free-threaded build of CPython versions below {}, the selected Python version is {}

What it means

Free-threaded (no-GIL) CPython builds are only supported by PyO3 from a minimum version onward (MIN_FREE_THREADED_VERSION). The build script errors when the selected interpreter is a free-threaded build older than that minimum.

Source

Thrown at pyo3-ffi/build.rs:108

                        }
                    } else {
                        error.add_help(format!(
                            "the free-threaded build of CPython {}.{} does not support the limited API so this check cannot be suppressed.", interp_version.major, interp_version.minor
                        ).as_str());
                        return Err(error.finish().into());
                    }
                }
                if env_var("PYO3_USE_ABI3_FORWARD_COMPATIBILITY").is_none_or(|os_str| os_str != "1")
                    && env_var("PYO3_USE_STABLE_ABI_FORWARD_COMPATIBILITY")
                        .is_none_or(|os_str| os_str != "1")
                {
                    error.add_help("set PYO3_USE_STABLE_ABI_FORWARD_COMPATIBILITY=1 to suppress this check and build anyway using the stable ABI");
                    return Err(error.finish().into());
                }
            }

            if interpreter_config.target_abi().kind().is_free_threaded() {
                ensure!(
                    interpreter_config.target_abi().version() >= MIN_FREE_THREADED_VERSION,
                    "PyO3 does not support the free-threaded build of CPython versions below {}, the selected Python version is {}",
                    MIN_FREE_THREADED_VERSION,
                    interpreter_config.target_abi().version(),
                );
            }
        }
        PythonImplementation::PyPy => {
            let versions = SUPPORTED_VERSIONS_PYPY;
            ensure!(
                interpreter_config.target_abi().version() >= versions.min,
                "the configured PyPy interpreter version ({}) is lower than PyO3's minimum supported version ({})",
                interpreter_config.target_abi().version(),
                versions.min,
            );
            // PyO3 does not support abi3, so we cannot offer forward compatibility
            if interpreter_config.target_abi().version() > versions.max {
                let error = MaximumVersionExceeded::new(interpreter_config, versions.max);

View on GitHub (pinned to ac9b6899d3)

Solutions

1. Upgrade to a free-threaded CPython build at or above the minimum supported version (e.g. 3.14t+)
2. Use a regular (GIL) CPython build instead of the 't' variant
3. Pin an older pyo3 version only if it supports your specific free-threaded build
4. Check the interpreter with python -c "import sysconfig; print(sysconfig.get_config_var('Py_GIL_DISABLED'))"

Example fix

// before
PYO3_PYTHON=/usr/bin/python3.13t cargo build  # preview 3.13 free-threaded
// after
PYO3_PYTHON=/usr/local/bin/python3.14t cargo build

import sysconfig
v = sys.version_info[:2]
ft = sysconfig.get_config_var("Py_GIL_DISABLED") == "1"
if ft:
    assert v >= (3, 14), f"free-threaded {v} too old for pyo3; need >= (3, 14)"

When it happens

Trigger: Selecting a free-threaded CPython interpreter (kind().is_free_threaded() == true, e.g. python3.13t) whose version is below PyO3's MIN_FREE_THREADED_VERSION, during pyo3-ffi build script configuration.

Common situations: Using an early/preview python3.13t or 3.14t free-threaded build; distro experimental no-GIL packages; CI matrices testing free-threaded wheels with an outdated interpreter.

Related errors

• the configured Python interpreter version ({}) is lower than
• Abi3t builds are not supported on CPython targets before Pyt
• Cannot target an abi3t version below {MINIMUM_SUPPORTED_VERS
• the configured PyPy interpreter version ({}) is lower than P
• the configured GraalPy interpreter version ({}) is lower tha

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