ImportError 名字无法导入：cannot import name 'xxx' 速查
更新时间：2026-10-24。FAQ 速查页，面向撞上
ImportError: cannot import name 'xxx' from 'yyy'的同学。这个报错和 ModuleNotFoundError 模块找不到速查 是兄弟俩：那边是模块整个找不到，这边是模块找到了、但你要的那个名字不在里面——版本太旧没这个符号、两个模块互相 import 卡成死锁、包作者忘了在__init__.py里导出、名字拼错或大小写不对、本地文件遮蔽了真包，外加 NameError 这种「根本没 import」的低配版。六根轴顺一遍基本必中。
本文要回答的问题
cannot import name 'xxx' from 'yyy'与No module named 'yyy'的分界线在哪？- 库里明明有这个函数，为什么 import 时说没有？
- 循环导入的报错长什么样，怎么一眼认出来？
from pkg import foo能用，为什么from pkg import bar就报 cannot import name？- NameError: name 'xxx' is not defined 和 ImportError 是什么关系？
一、报错原文与典型现象
三类原文要对号入座（工程路径以 /proj/demo 占位）：
$ python3 /proj/demo/main.py
Traceback (most recent call last):
File "/proj/demo/main.py", line 2, in <module>
from requests import Session2
ImportError: cannot import name 'Session2' from 'requests' (/usr/lib/python3/dist-packages/requests/__init__.py)$ python3 /proj/demo/main.py
ImportError: cannot import name 'helper' from partially initialized module 'pkg.core' (most likely due to a circular import) (/proj/demo/pkg/core.py)$ python3 /proj/demo/main.py
NameError: name 'Session' is not defined读报错先抓三点：报错行后半段的路径告诉你解释器实际摸到的是哪个文件——路径落在 site-packages 是真包，落在 /proj/demo/ 下是你自己的文件在遮蔽；带 partially initialized module 与 circular import 字样的是循环导入专属信号，不用往下猜；NameError 则是运行到那行时这个名字压根没绑定过——多半是忘了 import 或 import 那行自己先炸了被跳过。
二、病因处置速查表
| 报错现象 / 场景 | 可能原因 | 快速验证 | 处置 |
|---|---|---|---|
| 照教程写却 cannot import name | 装的版本太旧，该符号还没加入 | python3 -m pip show 包名 看 Version | python3 -m pip install -U 包名 |
| 升级后反而报这个错 | 新版改名/移除了该符号 | 查官方 changelog 或 python3 -c "import yyy; print(dir(yyy))" | 改用新名字，或 pin 回旧版 |
| 报错含 partially initialized / circular | 循环导入：a 引 b、b 又引 a | 画两个模块的 import 关系 | 把公共部分抽到第三个模块，或函数内延迟 import |
包内 from pkg import bar 失败、import pkg.core 能摸到 | __init__.py 没导出 bar | cat pkg/__init__.py | 在 __init__.py 加 from .core import bar |
| 名字看着一模一样仍报错 | 拼写/大小写错（Python 大小写敏感） | dir(模块) 列出真实符号逐个对 | 按 dir() 输出的真名改 |
| 路径指向 /proj/demo 下的本地文件 | 本地同名文件遮蔽真包 | 报错原文里的路径不在 site-packages | 重命名本地文件并清 __pycache__ |
| NameError: name 'xxx' is not defined | 忘了 import / import 行在 try 里被吞 | 搜全文有没有 import 该名字 | 补 import；别让 import 静默失败 |
| 解释器里能 import，脚本里不能 | 脚本运行目录有同名 .py 被优先捡到 | python3 -c "import yyy; print(yyy.__file__)" 分环境对比 | 统一从项目根跑，用 -m 方式 |
三、排查决策图
下面这张图是标准排查路线，颜色按角色区分：红是报错入口与命中的根因，蓝是排查动作，绿是通过分支，橙是修复动作，紫是防复发沉淀。
读这张图抓住两个检查点：先看报错原文里的路径——指向 /proj/demo/ 就直接判本地遮蔽，不用怀疑包本身；路径正常再用 dir() 把模块的真实符号清单打出来，你要的名字在不在、拼写差在哪、版本缺不缺，一张清单全回答。
四、逐条排查展开
版本里没有这个符号，是照抄教程翻车的主因。 教程写于新版本时代，你机器上是发行版源里的旧版本；或者反过来，新版把函数改名挪走了，旧教程还在教旧名字。确认手段一步双查：
python3 -m pip show requests # 看你装的版本
python3 -c "import requests; print(dir(requests))" # 看这个版本真实导出什么dir() 清单里有你要的名字却 import 失败，几乎只剩拼写问题；清单里没有，按教程要求 python3 -m pip install -U 包名 升级，或按 changelog 换新名字。
循环导入有专属指纹。 报错里带 partially initialized module 和 circular import 就不用排查别的了：a.py 顶部 from b import x，b.py 顶部 from a import y，谁先进来都撞上「对方只执行了一半」。两种修法按场景选：两个模块互相用的是同一个数据结构，把它抽到 common.py 里双双改从 common 引；只是某个函数用到对方，把 import 挪进函数体里延迟到调用时，模块加载期就解耦了。
init.py 没导出，是「包能用、名字不能」的根。 import pkg.core 好好的，from pkg import helper 却炸——因为后者走的是 pkg/__init__.py 的命名空间，作者没在里面 from .core import helper，这个名字对包外就不存在。自己写的包在 __init__.py 里集中维护导出清单；用别人的库就照文档的推荐路径引，别赌顶层一定导出。
拼写与大小写：Python 全部敏感。 Session 和 session、HTTPError 和 HttpError 都是不同符号。不要凭记忆写，从 dir() 输出里复制。NameError 同理——name 'Session' is not defined 八成是文件顶部那行 import 漏了，或者 import 被包在 try/except ImportError: pass 里静默吞掉了，这种「防御性 import」建议直接删，让它炸在明处。
本地遮蔽的确认姿势与模块篇同套。 报错原文路径不在 site-packages 就是铁证；python3 -c "import yyy; print(yyy.__file__)" 二次确认。把项目里的 requests.py、types.py 这类撞名文件改名，清掉旁边的 __pycache__，世界就清净了。
从模块导入和 from 导入的时机差，值得单独记一笔。 import a 只要求模块本身加载成功，from a import x 还要求加载完成的那一刻 a 的命名空间里已经有 x——这正是循环导入里 from 形式更容易炸的原因：import a 拿到的是「半成品模块对象」，属性访问推迟到运行时，往往碰巧能活；from a import x 当场点名，半成品里没有就死。所以解循环时除了抽公共模块和延迟 import，把 from 形式改成 import a 再在函数里用 a.x，也是常用的止血招——但别当成默认风格，它把依赖藏进了函数体，可读性变差，只用于拆环过渡期。
升级后的大面积 cannot import name，优先怀疑「锁版本」而不是改代码。 依赖树里某个传递依赖被 pip 顺手升了大版本，把你的直接依赖需要的旧符号删了——这时 pip show 看的是你直接依赖的版本，一切正常，病灶却在它的依赖上。python3 -m pip check 能列出依赖冲突，配合 pip install '肇事包<旧主版本' 钉回，比逐个改 import 快得多。
五、规范做法与预防
- requirements.txt 锁版本：教程、CI、同事三方版本一致，「版本没这个符号」不发生。
- 包内导出清单集中管：
__init__.py只放from .core import A, B和__all__，对外契约一目了然。 - 公共依赖下沉：两个模块要共享的东西放第三个模块，从结构上消灭环。
- 不写静默 import：
try: import x except ImportError: pass会把 ImportError 拖成远处的 NameError，排查成本翻倍。 - 文件名避开库名：同模块篇，新建脚本先想撞名。
- IDE 自动补全导入：让编辑器按真实符号补 import，拼写类错误写不出。
这一篇在知识体系里的位置
本篇是 Python 排错速查簇的「名字层」篇：模块整个找不到（No module named）看 ModuleNotFoundError 模块找不到速查；装包环节本身失败看 pip install 安装失败速查；环境怎么搭才不踩这些坑看 Python 入门导览。pip show 看版本、dir() 列符号、__file__ 辨遮蔽，三件确认套在所有 import 类报错间通用。
一句话总结
cannot import name 先看报错里的模块路径：指向本地文件就是同名遮蔽，改名清缓存；指向 site-packages 就 dir() 列真实符号——清单里有而导入失败是拼写大小写问题，清单里没有就 pip show 对版本，旧版升级、新版改名换名；带 partially initialized / circular 字样的直接按循环导入处理，公共依赖抽第三模块或函数内延迟 import；from pkg import x 失败而 import pkg.core 正常时去 __init__.py 补导出。requirements 锁版本加导出清单集中管，这类报错基本绝迹。