这是典型的 “同名文件覆盖官方包” 的导入报错；我现在联网核实官方文档、社区报错记录，以及 Python 和 TensorBoard 的导入机制。
Python 官方文档和 CPython 的问题跟踪记录都确认了这一点；我再补一条社区实修记录，核实 “改名并重启内核” 这条路径。
这个报错跟 TensorBoard 装没装、版本对不对基本无关，问题出在你项目里有一个叫 tensorboard.py 的文件，把官方包挡住了。完整报错是 No module named 'tensorboard.summary'; 'tensorboard' is not a package，后半句是关键指纹：Python 找到的 tensorboard 是一个 “普通模块”（单个 .py 文件），不是一个 “包”（有目录、有子模块），所以它没法继续往下找 summary 这个子模块。这类求助帖里的堆栈通常已经写明了证据 —— 出错脚本的路径就是 playground/tensorboard.py，同一份代码又去导 torch.utils.tensorboard，于是 Python 先撞上了自己家门口那个同名文件。修法只有五步：把本地文件改名（比如 train_with_board.py）、清掉对应的 __pycache__/tensorboard..pyc、彻底退出并重启解释器或 Jupyter 内核、用 importlib.util.find_spec 确认解析到 site-packages、再拿 SummaryWriter 写一个标量文件验证。千万别去删 site-packages 里那个真正的 tensorboard 目录。
先把报错文案逐字拆开，三句话对应三件事：
| 报错片段 | 它在说什么 | 说明什么 |
|---|---|---|
| No module named 'tensorboard.summary' | 找不到 tensorboard 下的 summary 子模块 | 上级名字已经解析到了某个东西，但那个东西里面没有 summary |
| 'tensorboard' is not a package | 被解析到的 tensorboard 没有包的属性 | 它是个普通模块，普通模块没有 __path__，无法继续查找子模块 |
| 堆栈里出现 .../playground/tensorboard.py | 出错脚本自己就叫 tensorboard.py | 同名遮蔽的直接证据 |
第二句的技术依据很硬：Python 官方文档对 “包” 的定义就是 —— 任何拥有 __path__ 属性的模块都被视为包；反过来，一个 .py 文件被导入后成为普通模块，没有 __path__，于是 tensorboard.summary 这条路径直接断掉。所以只要报错末尾带 is not a package，基本可以判定挡住它的是一个文件，而不是一个空目录。
机制这一层，讲清楚 “为什么本地文件能赢过 pip 装好的包” 就通了：
| 顺序 | 搜索位置 | 说明 |
|---|---|---|
| 1 | sys.modules 缓存 | 本次进程里已经导入过的，直接用缓存，不再找文件 |
| 2 | 脚本所在目录（sys.path[0]） | 运行 python xxx.py 时，插在标准库和 site-packages 之前 |
| 3 | 标准库路径 | 内置与标准库模块 |
| 4 | site-packages | pip／conda 装的三方包落在这里 |
也就是说，site-packages 排在最后。你 pip install tensorboard 装得再干净，只要当前目录里有个 tensorboard.py，第 2 步就已经命中了，第 4 步根本轮不到。Python 官方教程对此的措辞也很直白：脚本所在目录被放在搜索路径的最前面，这会带来一个需要留意的副作用 —— 同名文件会遮蔽标准库或三方库中的模块。
那 PyTorch 为什么非要去找 tensorboard.summary？因为它自己的封装层第一步就是导这个：
- 你写 from torch.utils.tensorboard import SummaryWriter。
- PyTorch 进到 torch/utils/tensorboard/__init__.py。
- 这个文件开头就执行 from tensorboard.summary.writer.record_writer import RecordWriter。
- 此时 tensorboard 解析到你本地那个 .py 文件，没有 summary 子模块，报错就在这一行炸出来。
链路清楚了，五步修复照着做就行：
| 步 | 动作 | 具体做法 | 验证点 |
|---|---|---|---|
| 1 | 改掉同名文件 | tensorboard.py → train_with_board.py（任何不含 tensorboard 的名字都行，tb.py 也可以） | 目录里不再有 tensorboard.py |
| 2 | 清本地缓存 | 删掉 __pycache__/tensorboard.*.pyc；若曾把 .pyc 直接放在目录里，一并清掉 | 没有残留的 tensorboard 字节码 |
| 3 | 彻底重启解释器 | 退出 IDE 的 Python Console、关掉再开脚本；Jupyter 执行 Restart Kernel | 新进程里不再有旧缓存 |
| 4 | 确认解析路径 | 跑下面的检查命令，origin 必须指向 site-packages | 路径不再是你的项目目录 |
| 5 | 端到端验证 | 用临时目录写一个标量，确认生成 event 文件 | 出现 events.out.tfevents.* |
第 4 步的检查命令，不导入 torch 也能跑，避免被二次污染：
import sys, importlib.util as u
spec = u.find_spec("tensorboard")
print("python:", sys.executable)
print("origin:", None if spec is None else spec.origin)
print("is package:", spec is not None and spec.submodule_search_locations is not None)
三个输出各有含义：origin 指向 /你的项目/.../tensorboard.py 就是遮蔽；is package 为 False 说明它是模块不是包；origin 为 None 才是真的没装。再补一条 python -m pip show tensorboard，确认这个解释器里到底有没有这个发行包，注意要用 -m，这样问的是你正在用的这个 Python，而不是 PATH 上随便那个 pip。
第 5 步的冒烟测试，别直接往项目真实日志目录写：
import tempfile
from torch.utils.tensorboard import SummaryWriter
with SummaryWriter(tempfile.mkdtemp(prefix="tb-check-")) as w:
w.add_scalar("check/value", 1.0, 0)
看到临时目录里冒出 event 文件，说明导入和写盘都通了，再把真实 log_dir 交进去。导入、写盘、界面读取是三件不同的事，分开验证才不会把 “路径问题” 误判成 “日志目录配错”。
六个最常见的误判，先看一眼能省半天：
| 做法 | 为什么没用 |
|---|---|
| pip uninstall tensorboard 再 pip install tensorboard | 装的是对的那个，被导入的是错的那个，重装不改导入顺序 |
| 升级 / 降级 TensorBoard 版本 | 版本问题会报别的文案，is not a package 不是版本问题 |
| 反复重装 torch、conda 与 pip 混着来 | 会把环境搞成两套，问题反而更多 |
| 往 PYTHONPATH 里追加 site-packages | sys.path[0] 依然在你前面，追多少都排在后面 |
| 换个目录跑一遍就好了，然后不改名 | 治标不治本，回到项目目录照旧报错 |
| 把文件改成 TensorBoard.py | Windows 文件系统大小写不敏感，照样遮蔽 |
顺手记一下几个同源变体，它们的根子是同一个：
| 报错文案 | 含义 | 是否同一根因 |
|---|---|---|
| No module named 'tensorboard.summary'; 'tensorboard' is not a package | 被解析成普通模块 | 是 |
| cannot import name 'SummaryWriter' from partially initialized module 'torch.utils.tensorboard' | 循环导入假象，实质是本地同名文件抢先 | 是 |
| 'module' object has no attribute 'SummaryWriter' | 导入到了错的模块对象 | 多数是 |
| No module named 'tensorboard.summary'（无后半句） | 可能真是没装，或目录里有空的 tensorboard 包 | 不一定 |
最后一行值得单独说：如果报错只有前半句、没有 is not a package，那被解析到的可能是个目录形式的包（有 __init__.py 但里面没有 summary），或者压根没装。这时候才轮到 “装包／查版本”，顺序不要颠倒。
预防比修复便宜，几条命名习惯值得固化：
- 脚本别用库名命名。tensorboard.py、torch.py、numpy.py、random.py 都属于高危名字，连 email.py、chess.py 这种也会翻车。
- 想表达 “带 board 的训练脚本”，用 train_with_board.py、train_tb.py 这类带前后缀的名字。
- 项目里如果确实需要一个叫 tensorboard 的目录做配置或输出，宁可叫 tb_logs、board_conf。
- 用 python -m 包.模块 启动时，sys.path[0] 变成当前工作目录（空字符串），遮蔽同样会发生，别以为换了启动方式就安全。
- 出现任何 xxx.yyy 形式的导入失败，先用 find_spec 看 origin，比盲目重装快得多。
【相关 FAQ】
问题 1：报错说 tensorboard 不是包，是不是说明 tensorboard 这个库本身有问题？
回答 1：不是。tensorboard 官方包当然是包，问题在于 Python 这次解析到的 tensorboard 不是它，而是你项目里那个同名 .py 文件。判据是报错末尾的 'tensorboard' is not a package：普通模块没有 __path__，所以 tensorboard.summary 无法继续查找。用 importlib.util.find_spec('tensorboard') 看 origin，如果指向你的项目目录，就说明官方包被本地文件挡住了，重装多少次都不会变。
问题 2：为什么把 tensorboard.py 改名之后，报错还是原样？
回答 2：因为改名只改了磁盘，没改内存。Python 的导入第一站是 sys.modules 缓存，当前进程里已经导入过的那个本地 tensorboard 模块对象还躺在缓存里，后续导入直接命中它，根本不会再去看文件系统。所以必须彻底退出解释器、关掉 IDE 的控制台、在 Jupyter 里执行 Restart Kernel，让新进程重新走一遍查找流程。改完名不重启，是这个 tensorboard 报错最常见的 “修不好” 原因。
问题 3：把 tensorboard.py 改名成什么比较稳妥，会不会影响已有的训练代码？
回答 3：只要新名字里不含 tensorboard 就行，train_with_board.py、train_tb.py 都是常见选择。改名影响的是 “这个脚本怎么被运行、被谁 import”，不影响它内部逻辑；如果别的文件里写了 import tensorboard（本来是想导你的脚本），那几处要同步改成新名字 —— 而这恰恰说明命名冲突早就埋下了。另外别改成 TensorBoard.py，Windows 大小写不敏感，照样遮蔽；也别只加下划线成 tensorboard_utils.py 就以为安全，名字里带 tensorboard 前缀在部分导入写法下仍可能踩坑，最稳的是完全避开这个词。
问题 4：确认是 tensorboard.py 同名冲突后，还需要检查别的什么？
回答 4：还要排三处。一看目录里有没有 tensorboard/ 文件夹（空的包目录会让报错丢掉 is not a package 那半句）；二看有没有残留的 __pycache__/tensorboard..pyc 或直接放在目录里的旧字节码；三看是不是有两个 Python——python -m pip show tensorboard 报 “已安装”、find_spec 却指向本地文件，就属于典型的 “装的那个解释器” 和 “跑代码的那个解释器” 不是同一个。三处都干净了，再用 SummaryWriter 往临时目录写一个标量做端到端验证。
【参考资料】
[2026-11-09]（No module named 'tensorboard.summary'; 'tensorboard' is not a package：先重命名自己的 tensorboard.py）阿里云开发者社区
[2026-11-08]（6. 模块）Python 官方文档 3.12 中文版
[2026-11-05]（5. The import system）Python 官方文档 3.15
[2026-11-03]（5. インポートシステム）Python 官方文档 3.11 日文版
[2026-09-07]（How to Fix ModuleNotFoundError: No Module Named 'package'）Python Developer Tooling Handbook
[2026-08-26]（'module' object has no attribute 'SummaryWriter'）Codemia
[2026-02-13]（Reliable way to check if a C module is a package）Discussions on Python.org
[2024-09-19]（
【已解决 含代码调试分析】pytorch 新手常见错误，文件 import 出现循环问题，可能是文件命名重复了）CSDN
[2021-02-14]（Learning Python and running into problems with PIP installed module）Stack Overflow
[2019-09-27]（Tensorboard in pytorch 1.1）PyTorch Forums
免责声明： 本文依据 Python 官方文档中关于导入系统、sys.path 搜索顺序、sys.modules 缓存与 “包” 定义的表述，PyTorch 官方论坛中 torch.utils.tensorboard 导入链的实现记录，以及阿里云开发者社区、Python Developer Tooling Handbook、Codemia、Stack Overflow、CSDN 等公开技术资料整理。需区分信息属性：sys.path[0] 为脚本所在目录、site-packages 排在最后、拥有 __path__ 的模块才被视为包、导入首先查询 sys.modules 缓存，这四条来自官方文档；torch/utils/tensorboard/__init__.py 开头执行 from tensorboard.summary.writer.record_writer import RecordWriter 来自论坛报错堆栈与源码，不同 PyTorch 版本的具体行号与措辞可能变化；is not a package 后缀指向 .py 文件属于依据导入机制的推断，并非官方专门声明，极少数情况下也可能由同名 .pyc 或特殊加载器造成。文中检查命令与冒烟测试在 Python 3.8+ 与常见 PyTorch 版本下通用，但具体版本约束、TensorBoard 最低版本要求请以你所在环境的 pip show 与项目依赖为准，不建议机械固定某个版本号。本文为技术排障说明，不构成对任何软件、发行包或第三方服务的推荐；操作前请确认改名对象是你自己的文件，不要删除 site-packages 中真正的 tensorboard 目录。
阿里云开发者社区Python Developer Tooling HandbookCodemiaPythonKiwix ServerPyTorchCSDN博客Discussions on Python.orgPython
本文来自作者[驰构内核]投稿，不代表乌兰科技网立场，如若转载，请注明出处：https://www.wlcbnews.com/rgzn/202611/576.html
评论列表（4条）
我是乌兰科技网的签约作者“驰构内核”！
希望本篇文章《tensorboard.summary 报 “不是包”先改掉你自己那个 tensorboard.py，重装一百次也没用》能对你有所帮助！
本站[乌兰科技网]内容主要涵盖：互联网行业的追踪与探索
本文概览：这是典型的 “同名文件覆盖官方包” 的导入报错；我现在联网核实官方文档、社区报错记录，以及 Python 和 TensorBoard 的导入机制。