PyO3/pyo3 · error

Unknown Py_GIL_DISABLED value

Error message

Unknown Py_GIL_DISABLED value

What it means

pyo3-build-config parses the interpreter config emitted by an already-running Python interpreter (via from_interpreter). Py_GIL_DISABLED must be "1", "0", or "None"; any other value means the reported config is unrecognizable, so parsing panics rather than guessing whether free-threading is enabled.

Source

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

        let shared = map["shared"].as_str() == "True";
        let python_framework_prefix = map.get("python_framework_prefix").cloned();

        let version = PythonVersion {
            major: map["version_major"]
                .parse()
                .context("failed to parse major version")?,
            minor: map["version_minor"]
                .parse()
                .context("failed to parse minor version")?,
        };

        let implementation = map["implementation"].parse()?;

        let gil_disabled = match map["gil_disabled"].as_str() {
            "1" => true,
            "0" => false,
            "None" => false,
            _ => panic!("Unknown Py_GIL_DISABLED value"),
        };

        let stable_abi = applicable_stable_abi(
            implementation,
            version,
            gil_disabled,
            abi3_version,
            abi3t_version,
        );

        let target_abi =
            PythonAbi::from_stable_abi(implementation, version, stable_abi, gil_disabled)?;

        let cygwin = map["cygwin"].as_str() == "True";

        let lib_name = if cfg!(windows) {
            default_lib_name_windows(
                target_abi,

View on GitHub (pinned to ac9b6899d3)

Solutions

1. Check what `import sysconfig; sysconfig.get_config_var('Py_GIL_DISABLED')` prints and upgrade/downgrade pyo3 to a version that understands it
2. Use a standard CPython release (or a pyo3 version matching the interpreter's development line)
3. Inspect the config passed to from_interpreter and fix the gil_disabled field to "0"/"1"/"None"

Example fix

// before (config map)
{"gil_disabled": "yes"}
// after
{"gil_disabled": "0"}

fn validate_gil_disabled(v: &str) -> Result<bool, String> {
    match v {
        "1" => Ok(true),
        "0" | "None" => Ok(false),
        other => Err(format!("unsupported Py_GIL_DISABLED value: {other}")),
    }
}

When it happens

Trigger: Calling from_interpreter with a config map whose gil_disabled value is anything other than "1", "0", or "None" — typically when the python-config JSON was produced by an unusual, patched, or newer interpreter emitting a novel value.

Common situations: Embedding a custom or vendor-patched CPython build whose sysconfig reports a different Py_GIL_DISABLED encoding; using a bleeding-edge free-threading build with format changes; hand-edited interpreter config files.

Related errors

• invalid hex encoding
• `pyo3_build_config::get()` requires a direct dependency on `
• Converting PyErr arguments failed: {}
• attempted to fetch exception but none was set
• failed to import exception {}.{}: {}

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