解决Python 报错：ModuleNotFoundError: No module named ‘pkg_resources‘的问题

0. 快速说明

遇到 ModuleNotFoundError: No module named 'pkg_resources' 问题

不要去升级 setuptools，而是执行 pip install "setuptools<82" 将它降级！

1. 踩坑背景

今天在跑一个深度学习项目的推理脚本（inference_stage2.py）时，遇到了一个极其诡异的报错。我的环境是配置好的，依赖也装全了，但只要程序一运行到加载 PyTorch 模型权重的环节，就会直接崩溃。

完整的报错信息如下：

Traceback (most recent call last):
  ...
  File "D:\Projects\miniconda3\envs\LHTD\lib\site-packages\pytorch_lightning\__init__.py", line 25, in <module>
    from lightning_fabric.utilities.seed import seed_everything  # noqa: E402
  File "D:\Projects\miniconda3\envs\LHTD\lib\site-packages\lightning_fabric\__init__.py", line 41, in <module>
    __import__("pkg_resources").declare_namespace(__name__)
ModuleNotFoundError: No module named 'pkg_resources'

报错提示找不到 pkg_resources 这个模块。

2. 排查过程

看到 No module named 'pkg_resources'，我的第一反应是：这通常是 setuptools 没有正确安装引起的。于是我进行了一系列常规操作：

升级并强制重装 setuptools (失败)

pip install --upgrade --force-reinstall setuptools

终端显示成功安装了最新的 setuptools-82.0.1，但在 Python 里测试 import pkg_resources 依然报错！

用 Conda 强制重装 (失败)

conda install -c conda-forge setuptools --force-reinstall

Conda 顺利跑完，但测试依然提示找不到模块。

甚至尝试了清缓存、查 sys.path (统统失败)

只要装的是最新的 setuptools，pkg_resources 就像是消失了一样。

3. 破案：根本原因

经过一番查找，终于发现了真相——这是 Python 包装生态最近的一次重大更新导致的。

pkg_resources 是 setuptools 库提供的一个包资源管理模块。由于它在运行时有一定的性能开销，Python 官方早在几年前就开始推荐使用内置的 importlib.metadata 和 importlib.resources 来替代它。

在 2026 年 2 月初，setuptools 发布了里程碑式的版本更新（版本号 82.0.0 及以上）。在这个版本中，官方正式、彻底地移除了 pkg_resources 模块！

这就导致了一个致命的断层：

• 你通过 pip install setuptools 或者 Conda 默认拉取到了最新的 82.x 版本（没有了 pkg_resources）。
• 但是你环境中安装的某些旧版第三方库（比如本例中的 pytorch_lightning / lightning_fabric），它们的源码里依然写着 import pkg_resources。
• 于是，由于底层依赖的抽离，哪怕你疯狂 reinstall、清缓存，代码也注定会崩溃。

4. 解决方案

知道原因后，解决起来就非常简单了。

方案 ：降级 setuptools

如果你不想或者不能升级代码里的第三方库（比如老项目需要固定的版本），直接将 setuptools 降级到 82.0.0 以下即可（最快、最稳妥的方法）。

执行以下命令：

pip install "setuptools<82"

降级完成后，再次测试：

python -c "import pkg_resources; print('pkg_resources found!')"
# 输出: pkg_resources found!

大功告成，之前的推理脚本终于可以顺利运行了。

5. 总结

在深度学习和 Python 开发中，我们经常遇到某个库昨天还好好的，今天重新建个虚拟环境就跑不通了。很大一部分原因就是某个底层依赖（如 setuptools, numpy, protobuf 等）发布了 Breaking Change (破坏性更新)。

到此这篇关于解决Python 报错：ModuleNotFoundError: No module named ‘pkg_resources‘的问题的文章就介绍到这了,更多相关Python 报错内容请搜索脚本之家以前的文章或继续浏览下面的相关文章希望大家以后多多支持脚本之家！

最新评论