Python 模块重名遮蔽标准库速查：ImportError 与 AttributeError 诡异现场

更新时间：2026-10-24。FAQ 速查页，面向「我就写了个 random.py，怎么就报错了」的同学。Python 模块重名遮蔽标准库是新手期最反直觉的一类报错：报错信息说「找不到 xx 属性」「模块被部分初始化」，但你的代码根本没碰那些东西——真相是 import 机制按 sys.path 顺序找模块，你本地的同名文件排在了标准库前面，把标准库「遮住」了。解释器 import 的其实是你的文件，文件里当然没有标准库那些函数。遮蔽的可怕之处在间接性：你的 random.py 不只是你自己 import 错，连 numpy 这种第三方库内部 import random 时拿到的也是你的文件，报错堆栈里全是别人的代码，锅却要算在你的文件名上。本篇给六个病因的识别与清理口径。

本文要回答的问题

• 为什么我没装任何东西，import random 却报 AttributeError？
• partially initialized module 这句话到底在说什么？
• 为什么报错堆栈里全是 numpy 的代码，问题却在我的文件？
• 明明删了同名文件，为什么还报一样的错？
• 怎么一眼判断当前 import 的是哪个文件？

一、报错原文与典型现象

真身（工程路径以 /proj/demo 占位）：

$ ls /proj/demo
random.py  main.py
$ python3 /proj/demo/main.py
Traceback (most recent call last):
  File "/proj/demo/main.py", line 1, in <module>
    import random
AttributeError: module 'random' has no attribute 'randint'
# 你的 random.py 里没有 randint——而解释器 import 的正是它，不是标准库

$ python3 /proj/demo/random.py
Traceback (most recent call last):
  File "/proj/demo/random.py", line 1, in <module>
    import random
  File "/proj/demo/random.py", line 2, in <module>
    print(random.randint(1, 10))
AttributeError: partially initialized module 'random' has no attribute 'randint' (most likely due to a circular import)
# 文件名撞标准库 + 文件内 import 自己 = 经典「部分初始化」报错

$ python3 -c "import numpy"
Traceback (most recent call last):
  ...
  File "/proj/demo/statistics.py", line 3, in <module>
AttributeError: module 'statistics' has no attribute 'mean'
# numpy 内部 import statistics，拿到的是你的 statistics.py——间接遮蔽

认清机制一句话：Python 的 import 是「按 sys.path 列表顺序、先到先得」，当前脚本所在目录默认排在标准库前面。同名文件的存在本身就是故障，跟你的代码写得对不对无关。

二、病因处置速查表

报错现象 / 场景	可能原因	快速验证	处置
AttributeError: module 'x' has no attribute 'y'	本地同名文件遮住标准库	python3 -c "import x; print(x.__file__)" 看路径	本地文件改名
partially initialized module	同名文件内又 import 同名模块	看报错文件路径是不是自己	改名，文件名永不与标准库同
报错堆栈全是第三方库代码	第三方库内部 import 被你的文件遮蔽	看堆栈最深处指向谁	改名你的文件，与库无关
删了同名文件还报错	残留的 __pycache__ 里 .pyc 仍在	目录下找 __pycache__	删掉同名文件与对应 pyc 缓存
同包名装了两次行为诡异	site-packages 里多来源重复安装	pip show 包名 看 Location	全部卸干净再装一次
虚拟环境里行为与系统 Python 不同	sys.path 顺序被 PYTHONPATH 打乱	python3 -c "import sys; print(sys.path)"	清理 PYTHONPATH，固定虚拟环境

三、排查决策图

这张图是模块遮蔽的标准动线：红是报错入口与定罪根因，蓝是排查动作，绿是验证通过，橙是修复动作，紫是防复发沉淀。

direction: down

hit: "诡异 ImportError / AttributeError"
which: "import 后打印 __file__\n看拿到的是哪个文件"
shadow: "路径指向本地同名文件\n遮蔽实锤；间接遮蔽查堆栈最深处"
root: "根因：同名文件 / 同名目录\n重复安装 / pyc 残留"
fix: "改名本地文件\n清 pycache / 卸干净重装"
retest: "重跑验证 __file__\n指向标准库或正确包"
prevent: "命名规范避开标准库名\nCI 检查目录下同名文件"

hit -> which
which -> shadow
shadow -> root
root -> fix
fix -> retest
retest -> prevent

hit.style: { fill: "#FDECEC"; stroke: "#D9534F" }
root.style: { fill: "#FDECEC"; stroke: "#D9534F" }
which.style: { fill: "#EAF2FE"; stroke: "#3B6FD4" }
shadow.style: { fill: "#EAF2FE"; stroke: "#3B6FD4" }
fix.style: { fill: "#FEF3E2"; stroke: "#E08A1E" }
retest.style: { fill: "#E9F8F0"; stroke: "#2E9E6B" }
prevent.style: { fill: "#F1ECFD"; stroke: "#7A5BD4" }

读这张图抓住主线：遮蔽问题的定位只有一个动作——print(模块.__file__)，看解释器拿到的到底是哪个文件。路径指向你的工程目录就是实锤，剩下只是「改谁的名、清谁的缓存」的执行问题。不要读报错文字猜语义，直接问解释器。

四、逐条排查展开

第一病因：本地文件与标准库同名。 最高发，没有之一：random.py、statistics.py、json.py、copy.py、code.py、email.py、test.py——新手起名喜欢「顾名思义」，而这些名字全是标准库模块。验证一条命令：

$ python3 -c "import random; print(random.__file__)"
/proj/demo/random.py
# 指向你的工程目录 = 遮蔽实锤；正常应指向 .../python3.11/random.py

处置：文件改名（加业务前缀，如 demo_random.py），改名后删掉同目录 __pycache__，重跑验证 __file__ 回到标准库路径。

第二病因：同名文件内 import 自己（部分初始化）。 报错 partially initialized module 'random' ... most likely due to a circular import 是专属信号：你的 random.py 第一行 import random，解释器按路径顺序找到你自己，模块对象刚开始执行就被自己引用，randint 还没定义出来，于是「部分初始化」。这个报错的「circular import」提示会误导你去找循环依赖——其实没有循环，只有同名。处置同上：改名。记住这个句式，见到它先查同名。

第三病因：同名目录/同名包遮蔽。 不只文件，目录也算：工程里有个 logging/ 目录（哪怕只是存日志的），只要里面有 __init__.py 或被当成命名空间包，就会遮蔽标准库 logging。同理，你自己写的包叫 tests/，会和无数库内部的 import tests.xxx 撞车。处置：目录改名，存放数据的目录永远不要带 __init__.py、不要起通用名。

第四病因：间接遮蔽——报错堆栈全是别人的代码。 最迷惑的一类：你只写了 import numpy，堆栈却在 numpy 深处炸开。原因：numpy 内部 import statistics（标准库），按路径顺序先找到你工程里的 statistics.py，调 statistics.mean 没有，炸在 numpy 的调用帧里。判别口诀：报错堆栈里最深的那个文件名，如果是你工程里的文件，锅就是你的，跟堆栈中间经过多少第三方库无关。这也是「为什么我的文件会影响 numpy」的答案——import 是全局命名空间，先到先得。

第五病因：同名包多来源重复安装。 pip 装了一份、conda 又装一份、pip install -e . 还链了一份，__file__ 指向谁取决于 path 顺序，行为时好时坏。验证：

$ pip show numpy | grep Location
$ python3 -c "import numpy; print(numpy.__file__, numpy.__version__)"
# 两处路径/版本对不上 = 重复安装

处置：pip uninstall 反复执行直到提示不存在，再装一次；科学计算栈统一单一来源。症状类似的还有「删了源文件但 pyc 缓存还在」——删掉同名 .py 后务必连 __pycache__/ 里对应的 .pyc 一起清，否则旧字节码仍可被加载（直接以脚本方式运行时尤其如此）。

第六病因：PYTHONPATH 与 sys.path 顺序错乱。 有人把工程目录塞进 PYTHONPATH 全局生效，结果所有项目互相可见，同名遮蔽从「单目录事故」升级成「跨项目事故」。验证：python3 -c "import sys; print(sys.path)"，看最前面几位是谁。处置：清空全局 PYTHONPATH，依赖走虚拟环境；工程内部引用用包结构加相对 import，不靠路径魔法。

定位万能钥匙。 一切遮蔽类问题，最终都收敛到一条命令：python3 -c "import <名字>; print(<名字>.__file__)"。打印出来的路径不属于预期位置，就是遮蔽；属于预期位置但还报错，那才是真正需要深查的 bug。把它当成本类问题的第一反应。

五、规范做法与预防

• 命名黑名单进团队规范：文件名/包名禁与标准库同名，高频雷区清单（random/statistics/json/code/test/logging/types/queue/email/select/signal）贴进新人手册。
• 起名加业务前缀：练手脚本叫 demo_random.py 而不是 random.py，从源头上消灭遮蔽。
• 删同名文件连缓存一起删：改名/删除后 rm -rf __pycache__，杜绝 pyc 残留复现。
• 虚拟环境隔离 + 单源安装：不用全局 PYTHONPATH，科学计算栈只用 pip 或只用 conda。
• CI 加同名检查：一行脚本扫描工程根目录文件名与 sys.stdlib_module_names 的交集，非空即拦（Python 3.10+ 直接可用该集合）。

这一篇在知识体系里的位置

本篇是 Python 排错速查簇的 import 机制篇，定位「同名遮蔽」这类反直觉报错：标准 ModuleNotFoundError 看 Python 模块找不到速查；语法层面报错看 Python 语法错误速查；装不上包看 pip install 失败速查 与 pip 依赖冲突装不上速查；网络调用报错看 ConnectionRefusedError 连接被拒速查；版本语义问题看 Python 版本不兼容报错速查。「__file__ 一问定位」这条心法对所有动态语言的 require/import 问题通用。

一句话总结

模块重名遮蔽的本质是 import 按 sys.path 先到先得、你的同名文件排在标准库前面，报错会以 AttributeError、partially initialized module、甚至第三方库堆栈深处炸开三种面孔出现，定位万能钥匙只有一条：python3 -c "import 名字; print(名字.__file__)" 看解释器拿到的是哪个文件；六因处置——本地同名文件改名、同名目录去 __init__.py 或改名、改名后连 __pycache__ 一起清、重复安装卸干净重装单一来源、清全局 PYTHONPATH 走虚拟环境；防复发主线一条：文件名永不与标准库同名，练手脚本一律加业务前缀，CI 用 sys.stdlib_module_names 自动拦截。