哪些主流库仍支持Python 3.7？兼容性检查清单

一、生态现状：为什么“最新版”基本不再支持 Python 3.7？

Python 官方根据 PEP 537 规划，于 2023 年 6 月正式停止对 Python 3.7 版本的安全漏洞补丁推送。伴随官方 EOL，由科学计算与工具链核心团队共同签署的 NEP 29（Python 库弃用计划标准）与 SPEC 0 规则生效：主流库只对发布日期前 42 个月内的 Python 版本提供支持。

这意味着，从 2022 年底至 2023 年年中，数据科学、机器学习、网络服务及底层工具库相继发布了切断 Python 3.7 支持的里程碑大版本。直接在 Python 3.7 环境中执行无版本限制的 pip install，轻则自动回退安装多年前的旧版本，重则因为次级依赖元数据解析错误引发安装中断或编译失败。

图 1：Python 3.7 生命周期与主流开源库支持演进

二、主流库兼容性检查清单：各领域最终支持版本

在必须使用 Python 3.7 的项目中，安装最新版库通常会遇到 requires-python >= 3.8 的阻断。以下按技术领域列出主流库对 Python 3.7 的最终可用稳定版本（Final Compatible Release）以及切断支持的关键版本，供锁定依赖时逐项对照。

图 2：主流库支持 Python 3.7 的最终稳定版本清单

1. 科学计算与数据分析库

2. 机器学习与深度学习框架

3. Web 框架与基础底层依赖

三、兼容性排查操作指南：四步锁定与验证依赖

在现有的 Python 3.7 项目中引入或调整依赖时，必须严格执行“探测-锁定-验证”流程，防止隐式拉取到不兼容的高版本 wheel 或未编译的源码包。

图 3：Python 3.7 依赖兼容性排查四步流程

步骤 1：确认环境与升级 pip 依赖解析器

早期 pip（如 20.2 之前版本）缺少严格的回溯解析能力，常因贪婪下载最新包导致错误。首先必须确认解释器版本，并将 pip 升级至 Python 3.7 允许的较新版本（pip 24.0 已弃用 3.7，建议保持 pip 23.0 - 23.3.2）：

# 1. 确认 Python 实际版本
python -V
# 示例输出：Python 3.7.16

# 2. 升级 pip 至支持 2020 解析器的稳定版本
python -m pip install --upgrade "pip>=20.3,<23.4"

步骤 2：使用 Dry-Run 试探解析过程

在直接向生产虚拟环境安装新库前，使用 --dry-run 选项观察 pip 最终决定的下载方案。如果看到某个依赖尝试下载 .tar.gz 源码包并在本地触发 C 编译器构建，往往意味着该包的预编译 wheel 已经不再向 Python 3.7 发布：

# 试探安装并输出解析计划，不实际更改环境
pip install --dry-run --report report.json "pandas" "requests"

检查生成的 report.json，确认所有下载项的 filename 均带有 cp37-cp37m 标签。如果出现源码构建错误，说明必须手动将该包降级到前述的兼容版本。

步骤 3：建立严格锁定的 requirements.txt 模板

在 Python 3.7 环境中，严禁在 requirements.txt 中使用模糊的大于等于号（>=）。必须全量使用双等号锁定主库及其关键中间件：

# Python 3.7 生产稳定基线示例
numpy==1.21.6
pandas==1.3.5
scipy==1.7.3
matplotlib==3.5.3

# Web 与通信组件
Flask==2.2.5
Werkzeug==2.3.8
requests==2.28.2
# 核心防爆锁：阻止 urllib3 升级至 2.x
urllib3>=1.26.0,<2.0.0

# 基础底层依赖
pydantic==1.10.14
typing-extensions==4.7.1
attrs==22.2.0
pytest==7.4.4

步骤 4：离线归档 Wheel 包防范上游变动

随着时间推移，部分开源包可能会因历史合规或打包清理下架旧版本，或者国内镜像源同步策略调整。最稳妥的工程化方式是在验证无误后，将全部 wheel 包下载到本地离线目录，通过 --no-index 部署：

# 1. 下载当前锁定版本的全部 wheel 包至 wheels/ 目录
pip download -r requirements.txt -d ./wheels

# 2. 在部署或容器启动时完全使用本地离线安装，断开网络干扰
pip install --no-index --find-links=./wheels -r requirements.txt

四、维护与平滑迁移策略：从维稳到升级

面对 Python 3.7 的全面停更，团队通常面临两条路线：短期原地维稳与中长期版本升级。

图 4：Python 3.7 遗留系统决策路径与升级演进

1. 无法升级系统时的原地加固策略

• 网络与物理隔离：Python 3.7 自带的标准库（如 http.server、ssl）已无法修复新公布的安全缺陷，切勿将 3.7 应用直接暴露在公网，应通过反向代理（如 Nginx）完成 TLS 终结与 WAF 拦截。
• 固化运行时镜像：将包含固定版本 wheel 的运行环境打包为不可变 Docker 镜像，不再在每次部署时动态拉取 PyPI。

2. 升级至 Python 3.8+ 的最小代码改动清单

如果决定启动升级，Python 3.7 到 3.8/3.9 的改动相对温和，主要关注以下几点：

• 标准库弃用清理：Python 3.7 中从 collections 直接导入 Mapping、Iterable 在 3.8+ 中会引发警告并在后续版本报错，需改为 from collections.abc import Mapping。
• 协程装饰器清理：弃用早期的 @asyncio.coroutine 和 yield from 语法，全面替换为标准的 async def 和 await。
• 解锁锁定的主版本：将 urllib3<2.0.0、numpy==1.21.6 等硬编码条件移出，允许 pip 拉取适配现代 Python 解释器的预编译二进制 wheel。

五、常见问题排查（FAQ）

Q1：为什么在 Python 3.7 环境下 pip 安装某些库时会卡在 Building Wheel 并报错 gcc / cl.exe 失败？

这是因为该库的最新版本已经停止为 Python 3.7 构建预编译的 Wheel 文件（.whl）。pip 匹配不到匹配 cp37 的二进制包，便自动下载了 .tar.gz 源码包并在本机触发 C/C++ 编译。如果本地没有配置相匹配的 C++ 编译工具链或依赖缺失，就会直接编译失败。解决方法是查找该库支持 Python 3.7 的最后一个 wheel 版本（参考前文清单），指定具体版本号安装。

Q2：pip 提示 SSL 证书错误或无法连接官方 PyPI 怎么办？

Python 3.7 构建年代较早，部分旧安装包内置的 OpenSSL 版本过旧，可能无法与现代 TLS 1.3 证书握手。建议使用国内支持历史协议的镜像源，或确保底层的 OpenSSL 升级至 1.1.1 的维护版本：

pip install -i https://pypi.tuna.tsinghua.edu.cn/simple/ -r requirements.txt