{"record":{"id":"34c9b58f38069d35","repo":"PyO3/pyo3","slug":"pyo3-does-not-support-the-free-threaded-build-of-c","errorCode":null,"errorMessage":"PyO3 does not support the free-threaded build of CPython versions below {}, the selected Python version is {}","messagePattern":"PyO3 does not support the free-threaded build of CPython versions below (.+?), the selected Python version is (.+?)","errorType":"console","errorClass":null,"httpStatus":null,"severity":"error","filePath":"pyo3-ffi/build.rs","lineNumber":108,"sourceCode":"                        }\n                    } else {\n                        error.add_help(format!(\n                            \"the free-threaded build of CPython {}.{} does not support the limited API so this check cannot be suppressed.\", interp_version.major, interp_version.minor\n                        ).as_str());\n                        return Err(error.finish().into());\n                    }\n                }\n                if env_var(\"PYO3_USE_ABI3_FORWARD_COMPATIBILITY\").is_none_or(|os_str| os_str != \"1\")\n                    && env_var(\"PYO3_USE_STABLE_ABI_FORWARD_COMPATIBILITY\")\n                        .is_none_or(|os_str| os_str != \"1\")\n                {\n                    error.add_help(\"set PYO3_USE_STABLE_ABI_FORWARD_COMPATIBILITY=1 to suppress this check and build anyway using the stable ABI\");\n                    return Err(error.finish().into());\n                }\n            }\n\n            if interpreter_config.target_abi().kind().is_free_threaded() {\n                ensure!(\n                    interpreter_config.target_abi().version() >= MIN_FREE_THREADED_VERSION,\n                    \"PyO3 does not support the free-threaded build of CPython versions below {}, the selected Python version is {}\",\n                    MIN_FREE_THREADED_VERSION,\n                    interpreter_config.target_abi().version(),\n                );\n            }\n        }\n        PythonImplementation::PyPy => {\n            let versions = SUPPORTED_VERSIONS_PYPY;\n            ensure!(\n                interpreter_config.target_abi().version() >= versions.min,\n                \"the configured PyPy interpreter version ({}) is lower than PyO3's minimum supported version ({})\",\n                interpreter_config.target_abi().version(),\n                versions.min,\n            );\n            // PyO3 does not support abi3, so we cannot offer forward compatibility\n            if interpreter_config.target_abi().version() > versions.max {\n                let error = MaximumVersionExceeded::new(interpreter_config, versions.max);","sourceCodeStart":90,"sourceCodeEnd":126,"githubUrl":"https://github.com/PyO3/pyo3/blob/ac9b6899d348be4d54614d060dea53a645a12e36/pyo3-ffi/build.rs#L90-L126","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Upgrade to a free-threaded CPython build at or above the minimum supported version (e.g. 3.14t+)","Use a regular (GIL) CPython build instead of the 't' variant","Pin an older pyo3 version only if it supports your specific free-threaded build","Check the interpreter with python -c \"import sysconfig; print(sysconfig.get_config_var('Py_GIL_DISABLED'))\""],"exampleFix":"// before\nPYO3_PYTHON=/usr/bin/python3.13t cargo build  # preview 3.13 free-threaded\n// after\nPYO3_PYTHON=/usr/local/bin/python3.14t cargo build","handlingStrategy":"validation","validationCode":"import sysconfig\nv = sys.version_info[:2]\nft = sysconfig.get_config_var(\"Py_GIL_DISABLED\") == \"1\"\nif ft:\n    assert v >= (3, 14), f\"free-threaded {v} too old for pyo3; need >= (3, 14)\"","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Only use 't' (free-threaded) interpreters from versions pyo3 explicitly supports","Verify Py_GIL_DISABLED in CI before selecting the interpreter","Keep regular and free-threaded interpreters in separate toolchain setups","Track pyo3 changelog for free-threaded support bumps"],"tags":["rust","python","free-threaded","nogil","version-compatibility"],"backgroundTag":"unsupported-python-version","analyzedSha":"ac9b6899d348be4d54614d060dea53a645a12e36","analyzedAt":"2026-09-05T09:20:35.319Z","contentChangedAt":"2026-09-05T09:20:35.319Z","schemaVersion":2},"datasetVersion":"2026-09-12T12:17:11.808Z"}