快速说明
遇到 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 (破坏性更新)。
