Python 3.14 free-threaded 构建如何确认解释器模式

我第一次给 Python 3.14 free-threaded 构建做并发试验时，最容易踩的坑不是线程代码，而是把“这个解释器支持无 GIL”和“这个进程当前关闭了 GIL”当成了同一件事。两者必须分开确认：脚本或 CI 先看 Py_GIL_DISABLED，实际启动后再看 sys._is_gil_enabled()。

官方地址：https://www.python.org/

Python 3.14 先确认“构建能力”，再确认“当前状态”

Python 官方文档给出的判断顺序很清楚。构建能力回答“这份 CPython 是否具备 free-threading 支持”，运行时状态回答“这次启动的进程是否真的没有 GIL”。前者适合写入启动检查和 CI，后者必须在目标参数与依赖导入完成后读取。

用一段检查脚本把两个结论同时打印出来

我更愿意把下面的检查放进启动日志，而不是依赖解释器文件名里的 t 后缀。后缀可以帮助人快速识别，真正给程序做决策时，还是应该读取构建配置和运行时函数。

# 先看发行版写入的版本描述，适合人工快速确认
python3 -VV

# 在目标解释器中分别读取构建能力与当前进程状态
python3 -c 'import sys, sysconfig; print("build_supports_free_threading:", sysconfig.get_config_var("Py_GIL_DISABLED") == 1); print("gil_enabled_now:", sys._is_gil_enabled())'

为了让判断更容易复用，也可以写成 Python 函数。这里的注释故意把两个变量分开命名：build_support 为真，不代表 gil_enabled 一定为假。

import sys
import sysconfig

# Py_GIL_DISABLED 判断构建能力，不判断本次进程的开关状态
build_support = sysconfig.get_config_var("Py_GIL_DISABLED") == 1
# _is_gil_enabled 判断当前主解释器此刻是否启用 GIL
gil_enabled = sys._is_gil_enabled()

print({
    "build_supports_free_threading": build_support,
    "gil_enabled_now": gil_enabled,
})

如果输出是 True / False，才可以把这次运行视为“具备 free-threaded 构建且当前没有 GIL”。如果是 True / True，通常不是构建失败，而是启动选项、环境变量或扩展导入改变了运行时状态。

为什么构建正确，运行时仍可能显示 GIL 已启用

free-threaded 构建保留了运行时开关。-X gil=1 或 PYTHON_GIL=1 会主动打开 GIL；相反，-X gil=0 或相应环境变量可以要求关闭。排查时要把启动命令、环境变量和真正导入的依赖一起记录，不能只复制一条裸的 python -c 结果。

尤其要注意 C 扩展。官方文档说明，如果扩展没有声明支持 free-threading，导入时可能重新启用 GIL，并给出警告。因此推荐的复查顺序是：

1. 在干净解释器中读取 Py_GIL_DISABLED。
2. 用和生产相同的 -X 参数与环境变量启动。
3. 导入应用的 C 扩展和核心依赖。
4. 最后再次读取 sys._is_gil_enabled()，同时保存警告日志。

从判断结果决定是否继续并发测试

只有“构建支持”和“当前关闭”两个条件同时满足，才值得比较多线程 CPU 任务的吞吐或延迟。若构建能力为假，应该换成 free-threaded 构建或回到多进程方案；若能力为真但状态为真，先处理启动开关和扩展兼容性，直接测性能只会得到另一种运行模式的结果。

这也解释了为什么不能把 free-threaded 当成无条件的加速开关：CPython 3.14 文档仍提醒它有额外开销，第三方扩展的支持情况也要单独确认。对于依赖大量原生扩展的应用，我会先做一条“导入后状态检查”，再决定是否扩大线程并行的灰度范围。

相关问题

看到 Python 版本号后缀带 t，就可以确定当前没有 GIL 吗？

不能。它更像 ABI 或构建形态的线索，当前进程仍可能被 -X gil、PYTHON_GIL 或扩展模块改变。最终以 sys._is_gil_enabled() 为准。

普通 GIL 构建能用 sys._is_gil_enabled() 判断什么？

它可以告诉你当前进程的 GIL 状态，但普通构建没有 free-threading 能力；需要判断是否值得尝试无 GIL 模式时，先看 Py_GIL_DISABLED。

为什么无 GIL 进程还要检查扩展模块？

因为未声明 free-threading 支持的 C 扩展可能在导入时让 GIL 重新启用。应用级检查必须放在关键依赖导入之后，而不是只检查 Python 启动瞬间。