快速说明
遇到 ModuleNotFoundError: No module named 'pkg_resources' 问题
不要去升级 setuptools,而是执行 pip install "setuptools<82" 将它降级!
踩坑背景
今天在跑一个深度学习项目的推理脚本(inference_stage2.py)时,遇到了一个极其诡异的报错。我的环境是配置好的,依赖也装全了,但只要程序一运行到加载 PyTorch 模型权重的环节,就会直接崩溃。
完整的报错信息如下:
报错提示找不到 pkg_resources 这个模块。
排查过程
看到 No module named 'pkg_resources',我的第一反应是:这通常是 setuptools 没有正确安装引起的。于是我进行了一系列常规操作:甚至尝试了清缓存、查 sys.path (统统失败)
只要装的是最新的 setuptools,pkg_resources 就像是消失了一样。
用 Conda 强制重装 (失败)
conda install -c conda-forge setuptools --force-reinstall
Conda 顺利跑完,但测试依然提示找不到模块。
升级并强制重装 setuptools (失败)
pip install --upgrade --force-reinstall setuptools
终端显示成功安装了最新的 setuptools-82.0.1,但在 Python 里测试 import pkg_resources 依然报错!
根本原因
经过一番查找,终于发现了真相——这是 Python 包装生态最近的一次重大更新导致的。
pkg_resources 是 setuptools 库提供的一个包资源管理模块。由于它在运行时有一定的性能开销,Python 官方早在几年前就开始推荐使用内置的 importlib.metadata 和 importlib.resources 来替代它。
在 2025 年 2 月初,setuptools 发布了里程碑式的版本更新(版本号 82.0.0 及以上)。在这个版本中,官方正式、彻底地移除 pkg_resources 模块!
这就导致了一个致命的断层:你通过 pip install setuptools 或者 Conda 默认拉取到了最新的 82.x 版本(没有了 pkg_resources)。但是你环境中安装的某些旧版第三方库(比如本例中的 pytorch_lightning / lightning_fabric),它们的源码里依然写着 import pkg_resources。于是,由于底层依赖的抽离,哪怕你疯狂 reinstall、清缓存,代码也注定会崩溃。
解决方案
知道原因后,解决起来就非常简单了。
方案:降级 setuptools
如果你不想或者不能升级代码里的第三方库(比如老项目需要固定的版本),直接将 setuptools 降级到 82.0.0 以下即可(最快、最稳妥的方法)。
执行以下命令:
pip install "setuptools<82"降级完成后,再次测试:
大功告成,之前的推理脚本终于可以顺利运行了。
总结
在深度学习和 Python 开发中,我们经常遇到某个库昨天还好好的,今天重新建个虚拟环境就跑不通了。很大一部分原因就是某个底层依赖(如 setuptools, numpy, protobuf 等)发布了 Breaking Change (破坏性更新)。

