PyO3/pyo3 · error

build_flags contains Py_GIL_DISABLED but target_abi '{target

Error message

build_flags contains Py_GIL_DISABLED but target_abi '{target_abi}' is not free-threaded

What it means

Consistency error raised while reconciling the ABI selected via PYO3_CROSS_PYTHON_ABI / cargo features with the build flags parsed from sysconfigdata: the flags contain Py_GIL_DISABLED (interpreter is free-threaded) but the configured target_abi is not a free-threaded kind, so the two sources of truth disagree.

Source

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

            (Some(target_abi), false) => target_abi,
            // Target ABI set + Py_GIL_DISABLED: reconcile.
            (Some(target_abi), true) => match target_abi.kind() {
                // abi3 + Py_GIL_DISABLED: the abi3 feature is a no-op on free-threaded
                // interpreters, so for backward compatibility fall back to a free-threaded
                // version-specific build.
                PythonAbiKind::Stable(StableAbi::Abi3) => {
                    let new_abi =
                        PythonAbiBuilder::new(target_abi.implementation(), target_abi.version())
                            .free_threaded()
                            .finalize()?;
                    warn!(
                        "Targeting an abi3 build but build_flags contains Py_GIL_DISABLED, \
                         falling back to a version-specific free-threaded build"
                    );
                    new_abi
                }
                // GIL-enabled version-specific + Py_GIL_DISABLED is contradictory.
                PythonAbiKind::VersionSpecific(GilUsed::GilEnabled) => bail!(
                    "build_flags contains Py_GIL_DISABLED but target_abi \
                     '{target_abi}' is not free-threaded"
                ),
                // Already free-threaded (Stable(Abi3t) or VersionSpecific(FreeThreaded)).
                _ => target_abi,
            },
        };
        if target_abi.kind().is_free_threaded() {
            build_flags.0.insert(BuildFlag::Py_GIL_DISABLED);
        }
        #[expect(
            deprecated,
            reason = "constructing an InterpreterConfig directly, need to write to fields"
        )]
        Ok(InterpreterConfig {
            implementation: self.implementation,
            version: self.version,
            shared: self.shared,

View on GitHub (pinned to ac9b6899d3)

Solutions

1. Set PYO3_CROSS_PYTHON_ABI (or the cargo abi3 selection) to the free-threaded ABI matching the interpreter
2. Remove Py_GIL_DISABLED from the interpreter/sysconfigdata being targeted, or point the build at a GIL-enabled interpreter
3. Let the build script auto-derive the ABI instead of pinning a conflicting one

When it happens

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