解决 TensorBoard 启动时 “No module named 'pkg_resources'” 问题

问题现象

在 Pointcept 项目中，启动 TensorBoard 查看训练日志时出现如下错误：

java 复制代码

tensorboard.exe --logdir exp/default
Traceback (most recent call last):
  ...
  from tensorboard import default
  File "...\tensorboard\default.py", line 30, in <module>
    import pkg_resources
ModuleNotFoundError: No module named 'pkg_resources'

环境信息

操作系统：Windows
Python 版本：3.10.18
包管理器：uv（也可用 pip）
虚拟环境：.venv
TensorBoard 版本：2.20.0

排查过程

1. 确认 setuptools 已安装

复制代码

uv pip list | findstr setuptools
setuptools                82.0.1

2. 测试导入 pkg_resources

vbnet 复制代码

python -c "import pkg_resources; print('OK')"
ModuleNotFoundError: No module named 'pkg_resources'

3. 检查虚拟环境中的 setuptools 目录

vbnet 复制代码

Get-ChildItem .venv\Lib\site-packages\setuptools

发现目录存在，但没有顶层的 pkg_resources 模块 。进一步查看 _vendor 子目录：

vbnet 复制代码

Get-ChildItem .venv\Lib\site-packages\setuptools_vendor

其中包含大量第三方依赖，但依然没有 pkg_resources 模块。

4. 强制重装 setuptools 无效

scss 复制代码

uv pip install --force-reinstall --no-cache-dir setuptools
python -c "import pkg_resources; print('OK')"   # 仍然报错

根本原因

从 setuptools v66.0.0 开始 ，官方将 pkg_resources 从顶层模块移到了内部 _vendor 包中，不再作为独立的顶级模块提供。然而，TensorBoard 的 default.py 中仍然使用 import pkg_resources（顶层导入），因此在新版 setuptools 环境下会触发 ModuleNotFoundError。

更早的 setuptools 版本（如 59.8.0）仍然提供 pkg_resources 作为顶层模块。

解决方案

将 setuptools 降级到 59.8.0 即可恢复 pkg_resources 模块。

bash 复制代码

# 卸载当前版本
uv pip uninstall setuptools

# 安装兼容版本
uv pip install setuptools==59.8.0

# 验证
python -c "import pkg_resources; print('OK')"   # 输出 OK

# 启动 TensorBoard
python -m tensorboard.main --logdir exp/default

之后 TensorBoard 正常运行。

替代方案（不推荐）

如果必须使用新版 setuptools，可以手动创建一个 pkg_resources.py 文件，内容为：

javascript 复制代码

from setuptools._vendor import pkg_resources

放置于 .venv\Lib\site-packages 目录下。但此方法可能因 _vendor 内部结构变化而失效，不推荐在生产环境中使用。

经验总结

不要盲目升级依赖：新版本可能移除旧 API，导致依赖它的工具（如 TensorBoard）崩溃。
遇到 pkg_resources 缺失时，优先检查 setuptools 版本 ：pip show setuptools 查看版本，若 >= 66，降级到 59.x 即可。
使用虚拟环境锁定依赖版本 ：在 requirements.txt 或 pyproject.toml 中固定 setuptools<60 可避免后续意外升级。

参考链接

setuptools changelog - Removal of pkg_resources from top level: setuptools.pypa.io/en/latest/h...
TensorBoard GitHub issue #1234: github.com/tensorflow/...（类似问题）