【已解决】ModuleNotFoundError: No module named 'pkg_resources' | Setuptools 82.0.0+ 版本断层深度复盘

---

目录

【已解决】ModuleNotFoundError: No module named 'pkg_resources' | Setuptools 82.0.0+ 版本断层深度复盘

📌 问题描述

🔍 深度追溯：为什么“保持最新”反而崩了？

1. Setuptools 82.0.0 的激进变更

2. 习惯性升级的“副作用”

3. 下游生态的滞后

🛠️ 终极解决方案

方案一：强制降级（最快、最稳妥，推荐！）

方案二：修改项目源码（不推荐，仅限紧急情况）

📚 权威引用与官方说明

💡 避坑指南 & 总结

---

ComfyUI 更新后 ModuleNotFoundError: No module named ‘pkg_resources‘报错修复指南

📌 问题描述

在 Windows/Linux/macOS 环境下，许多开发者在创建新的 Python 虚拟环境后，习惯性地执行以下“基础环境升级”命令：

python -m venv --copies .venv
.\.venv\Scripts\activate
# 习惯性动作：升级基础构建工具
python -m pip install -U pip setuptools wheel 

随后运行项目（如 FunASR, ModelScope, PyTorch, Jupyter 等）时，突然触发报错：

Traceback (most recent call last):
  File "...", line 18, in <module>
    import pkg_resources
ModuleNotFoundError: No module named 'pkg_resources'

即使你尝试再次 pip install setuptools，系统也会提示 Requirement already satisfied，但程序依然无法运行。

---

🔍 深度追溯：为什么“保持最新”反而崩了？

https://setuptools.pypa.io/en/latest/history.html#pkg-resources

1. Setuptools 82.0.0 的激进变更

2025 年初，setuptools 发布了 82.0.0 版本。
在此版本中，官方正式调整了内部模块结构，将存在了十几年的 pkg_resources 彻底从默认导入路径中移除或剥离。

2. 习惯性升级的“副作用”

以往我们认为 pip install -U setuptools 是最佳实践。但在 Setuptools 82.0.0+ 发布后，这一操作会将你的环境推向一个不再兼容旧代码的状态。

3. 下游生态的滞后

大量主流深度学习和 AI 框架（如阿里 ModelScope）的底层代码仍在使用 import pkg_resources 来管理插件。由于这些库尚未完成向 importlib.metadata 的迁移，直接导致了环境断层。

---

🛠️ 终极解决方案

方案一：强制降级（最快、最稳妥，推荐！）

由于 pkg_resources 在 81.x 版本中仍保留了兼容层，我们只需要将 setuptools 强制锁定在 82.0.0 版本以下 即可。

在你的虚拟环境中执行：

# 强制重新安装 81.0.0 版本
python -m pip install "setuptools<82.0.0" --force-reinstall

验证是否修复：

python -c "import pkg_resources; print('Found it!')"

如果输出 Found it!，问题即刻解决！

---

方案二：修改项目源码（不推荐，仅限紧急情况）

如果无法降级环境，你需要找到报错的文件（如 modelscope/utils/plugins.py），将 import pkg_resources 修改为：

try:
    import pkg_resources
except ImportError:
    import importlib.metadata as pkg_resources

---

📚 权威引用与官方说明

1. 官方弃用公告：Setuptools pkg_resources Deprecation

   官方明确指出： pkg_resources API 已被标记为 Legacy，计划最快于  2025-11-30 彻底物理移除。

2. 版本更新日志：Setuptools v82.0.0 Changelog

   确认了对内部包发现机制的重大调整，导致旧式导入失效。

---

💡 避坑指南 & 总结

1. 慎用 -U 参数：在生产环境或运行成熟框架（如 FunASR/ModelScope）时，不要连带升级 setuptools 到最新版。
2. 锁定版本：在你的 requirements.txt 或环境配置文档中，建议明确标注 setuptools==81.0.0。
3. 关注 Warning：当你在日志中看到 UserWarning: pkg_resources is deprecated 时，请务必提前做好版本锁定，否则下一次环境重建（rebuild）时项目必崩。

---

标签： #Python #Setuptools #pkg_resources #ModuleNotFoundError #虚拟环境 #ModelScope #FunASR

---

希望这篇博文能帮到正在排坑的同学！如果你觉得有用，请 点赞、收藏、关注 三连！🚀

---