外观
为什么换个启动目录就导入失败:模块、包与 import 执行过程
摘要
把一个脚本拆成多个文件后,换个目录启动就找不到模块,循环导入还会读到半初始化状态。本文面向 Python 初学者,从目录结构与启动方式出发,讲清模块对象、导入缓存、包上下文和可运行的故障复现。
1. 场景:同一份代码,启动方式改变就失败
这是一个教学场景:日志工具拆成 logtool/main.py 与 logtool/parser.py,入口中写 from .parser import parse。从项目根目录执行 python logtool/main.py 报相对导入错误,执行 python -m logtool.main 却能工作。还有人把工具文件命名为 json.py,结果原本正常的 import json 读到了本地文件。源码没变,错误却由启动方式和名字引发。
import(导入)既寻找模块,也在当前代码环境建立名称绑定;模块加载还可能执行代码。module(模块)通常对应一个 .py 文件,但也可以来自内置实现、扩展模块或其他加载形式。package(包)能够包含子模块并提供相应包路径。建立“导入就是文本粘贴”的模型,会错过缓存、对象身份和初始化顺序。
先按失败阶段分叉:名字是否定位到模块,模块对象是否已建立,所需属性是否已初始化。 Shell 命令路径、Python 模块完整名和文件路径分别属于不同层;找到一个文件不证明它已成功执行。模块名也不是把点号替换成斜杠就能覆盖全部加载方式。
保持 a/b 两个模块不变,预测 b 回读 a.token 的时刻:a 已登记缓存,但还没执行 token 赋值,所以不会重新创建 a,却仍然读不到属性。这个时间窗口把“找不到模块”和“模块部分初始化”分开。后面先观察 finder/spec,再用同一个包的依赖重构检验修复发生在哪一阶段。
2. 模块是拥有命名空间的对象
namespace(命名空间)是名称与对象关联的集合。模块顶层定义函数、类和变量时,名称进入模块命名空间。import parser 通常把模块对象绑定为本地 parser,访问函数时写 parser.parse(...);from parser import parse 把模块中当前的 parse 对象绑定为本地名称。它不是建立一个永远自动同步的变量链接。
比如模块有 settings = {},from module import settings 得到同一字典引用,模块后来原地修改字典,本地能看见;若模块把 settings 重绑到新字典,本地旧引用不会自动改绑。这沿用了第三篇的对象模型,没有新的“导入变量特例”。共享可变状态可能跨所有使用该模块的调用存在,不能因为对象在另一个文件里就认为它隔离。
导入会执行模块顶层语句,包括定义、赋值,以及你写在顶层的函数调用。所以模块顶层打开数据库、下载文件或启动线程,会让“导入一个函数”变成外部副作用。建议把资源获取放在显式启动或生命周期管理函数中,导入阶段保留必要定义和有界初始化。它也更容易做测试与排障,不必为了查看一个函数就连外部服务。
普通情况下,同一个解释器内相同完整名称的模块经缓存返回,所以顶层代码通常在首次成功加载时执行。这里强调同一名称与同一解释器:重新加载、手动操作缓存、不同名称加载同一文件,或多个解释器,都可以改变这个行为。官方教程介绍模块与命名空间,见 模块教程。
3. 导入执行链:先缓存,再查找,再初始化
导入首先按完整模块名检查 sys.modules,它是解释器保存已加载模块对象的映射。存在有效模块时通常直接使用;找不到才进入后续搜索。搜索机制包含 finder(查找器)与 loader(加载器):前者给出模块来源及加载说明,后者准备并执行模块。默认路径查找器使用相关路径,但内置和冻结模块并不等同于普通文件搜索。
加载器通常先创建模块对象,并在执行模块代码之前把它放入 sys.modules。这样模块代码直接或间接再次导入自己时,不会无限重复创建和执行。副作用是其他模块可能拿到还没执行完的模块对象,某些属性尚不存在。循环导入错误中的 partially initialized module(部分初始化模块),就源于这段时间窗口,而不是随机找错了磁盘文件。
模块执行失败时,正在失败的加载会清除其相应缓存项;之前已成功加载的其他模块不因此全部撤销。不要假设一次失败会回滚所有导入副作用,也不要在长生命周期进程里靠反复导入模拟事务。官方导入规范明确描述缓存、创建时点与失败清理,见 导入系统。
图表将在阅读到此处时加载…
缓存不只是为了快。它还让模块级状态和类对象身份在正常导入中保持一致。手动从 sys.modules 删除一个条目再导入,可能创建第二个模块对象;旧引用仍保留旧对象,导致同名类之间的身份判断出乎意料。importlib.reload 重执行现有模块也有复杂行为,不能当成可靠线上热修复工具。
4. 包上下文决定相对导入,启动方式决定初始条件
一个常规包可以包含 __init__.py,导入包时执行它。Python 还支持没有该文件的 namespace package(命名空间包),用于按特定规则组合包位置;因此“不含 __init__.py 就绝对不是包”是错误概括。初学项目先使用明确的常规包布局,不为省一个空文件增加理解成本。
以下结构示意日志工具,内容必须遵循包关系:
text
project/
└─ logtool/
├─ __init__.py
├─ main.py
└─ parser.pyfrom .parser import parse 中的点表示相对于当前包,不是相对于当前工作目录。python -m logtool.main 按模块名寻找并执行入口,提供包上下文;直接把 main.py 当脚本执行,通常没有相同包上下文,因此相对导入失败。不是靠文件放在某个文件夹里就自动知道完整包身份。
常规直接脚本启动时,相关搜索路径通常包含脚本所在目录;-m 方式通常将当前目录放入初始相关路径。具体环境、隔离选项和发行方式可以调整这些规则,所以排查仍应查看实际 sys.path 和模块说明,而不是只记默认第一项。PYTHONPATH 可以添加搜索位置,但全局配置它容易把开发机上的特殊路径变成隐含依赖。项目应通过合理启动与安装方式建立导入关系,第十四篇会给出可安装布局。
__name__ 在直接执行入口中通常为 "__main__",在正常导入中是模块名;入口保护只决定那一块代码是否执行,不阻止模块其他顶层语句运行。包上下文还与模块说明 __spec__ 等信息有关,不能简单让字符串 __name__ 变成点号名称就认为相对导入已经正确。官方教程与规范对主模块作了专门说明。
5. 循环导入:调整依赖方向比推迟错误更可靠
假设 a.py 先导入 b,后定义 token;b.py 又执行 from .a import token。导入 a 时,它已经在缓存里但 token 尚未建立,b 读取失败。问题是读取发生在目标初始化完成之前,而不是两个模块之间任何依赖都必然不合法。如果 b 暂时只导入模块对象,稍后再访问属性,某些写法可能运行,但仍要明确调用时间。
推荐先识别依赖职责:共享数据类型和常量可放到第三个低层模块,两边依赖它;业务组合留到更高层入口,避免底层模块反向依赖启动层。局部导入能把读取推迟到函数调用时,在某些可选依赖场景有用,但不能替代清晰依赖方向。若模块必须在导入时调用对方,简单把一条 import 移进函数可能只是把错误拖到运行请求时。
同样避免在 __init__.py 中无限扩展导出。看似方便的 from .service import Service 可能触发一整条依赖链,子模块再反向从包根读取又形成循环。公开 API 要有选择地组织,不要让导入任意子模块都启动整个应用。定义最小依赖图,通常比对着部分初始化错误不停调换行顺序更稳定。
6. 最小实验:缓存和部分初始化状态
按时间线预读:查找 state 的 spec 不应执行这个子模块;第一次 import 才输出 module executed,第二次返回同一对象。a 导入 b 时 token 尚未赋值,回读失败;提取 shared 后,a/b 都从没有回指的共享模块取得 ready。两条成功路径分别验证缓存身份与依赖方向,不能互相代替。
完整程序在 08_imports.py。它在临时目录创建教学包,结束后清理自己的路径和缓存项,不修改生产模块:
python
"""临时教学包展示缓存、模块对象与部分初始化状态。"""
import importlib
import importlib.util
from importlib.machinery import PathFinder
from pathlib import Path
import sys
from tempfile import TemporaryDirectory
def main():
name = "python_series_import_demo"
with TemporaryDirectory() as directory:
root = Path(directory)
package = root / name
package.mkdir()
(package / "__init__.py").write_text("", encoding="utf-8")
(package / "state.py").write_text(
"print('module executed')\nvalues = []\n", encoding="utf-8")
# a 在设置 token 之前导入 b,而 b 又读取 a 的 token。
(package / "a.py").write_text(
"from . import b\ntoken = 'ready'\n", encoding="utf-8")
(package / "b.py").write_text(
"from .a import token\n", encoding="utf-8")
sys.path.insert(0, directory)
importlib.invalidate_caches()
try:
spec = importlib.util.find_spec(f"{name}.state")
assert spec is not None and spec.origin == str(package / "state.py")
assert spec.loader is not None
finder_spec = PathFinder.find_spec(f"{name}.state", [str(package)])
assert PathFinder in sys.meta_path
assert finder_spec is not None and finder_spec.origin == spec.origin
assert f"{name}.state" not in sys.modules # 查找不执行子模块。
print("finder/spec:", PathFinder.__name__, spec.name)
print("spec loader:", type(spec.loader).__name__)
first = importlib.import_module(f"{name}.state")
second = importlib.import_module(f"{name}.state")
assert first is second
first.values.append("event")
assert second.values == ["event"]
try:
importlib.import_module(f"{name}.a")
except ImportError:
print("circular import rejected")
else:
raise AssertionError("expected circular import failure")
# 修复同一个包:把共享 token 移到无回指依赖的模块。
(package / "shared.py").write_text("token = 'ready'\n", encoding="utf-8")
(package / "a.py").write_text(
"from .shared import token\nfrom . import b\n", encoding="utf-8")
(package / "b.py").write_text("from .shared import token\n", encoding="utf-8")
for suffix in ("a", "b"):
sys.modules.pop(f"{name}.{suffix}", None)
# 源码重写可能与旧 pyc 同秒同尺寸;删除自己的缓存避免假成功。
for cached in (package / "__pycache__").glob("[ab].*.pyc"):
cached.unlink()
importlib.invalidate_caches()
repaired = importlib.import_module(f"{name}.a")
assert repaired.token == repaired.b.token == "ready"
print("same package repaired:", repaired.token)
print("cached:", first is second)
finally:
sys.path.remove(directory)
for key in list(sys.modules):
if key == name or key.startswith(name + "."):
sys.modules.pop(key)
if __name__ == "__main__":
main()执行 python docs/python/examples/08_imports.py。预期 module executed 仅输出一次,随后是 circular import rejected 和 cached: True。先成功导入 state 两次并修改共享列表,说明缓存返回相同模块对象;再导入循环依赖,说明缓存存在不代表属性已初始化完成。异常类型被验证,不依赖不同版本中错误消息全文一致。
invalidate_caches 通知查找器清理某些查找缓存,不是清空 sys.modules。本例因为运行时创建新包而显式调用,避免把文件创建后的发现行为当成无条件即时刷新。finally 的缓存清理只针对专用教学名称;业务程序不要照搬为“每次使用后卸载模块”,那会破坏共享状态并制造新身份。
7. 导入失败的排查顺序与踩坑
先确认解释器身份,排除第一篇的环境错位;再确认完整模块名、启动命令和当前目录。若成功导入了错误模块,检查 module.__file__(若存在)及 module.__spec__,它们比凭名字猜位置可靠。内置模块可能没有普通文件路径,因此不要把没有 __file__ 一概当失败。
本地文件遮蔽是具体高频坑:命名为 json.py、typing.py 或第三方包名字的脚本可能在相关搜索优先级下先被找到。改名后重新启动进程,再核对来源;仅修改文件名而继续使用旧进程,缓存里还可能保留此前模块。不要盲目把 site-packages 加到最前面来绕过遮蔽,它会引入更隐蔽的路径依赖。
ModuleNotFoundError 也可能来自已经找到的模块内部。如果 import service 报缺少 dbclient,应处理真正缺失的内部依赖,而不是反复寻找 service.py。完整异常栈会指出加载阶段正在执行哪个文件。循环导入则画初始化顺序,找到谁提前访问了未建立属性,再调整依赖职责。
.pyc 是编译代码缓存,不是运行状态缓存。__pycache__ 中存在文件,并不说明模块一定能被当前环境成功导入,也不意味着顶层代码不再执行。它主要帮助减少相应编译工作,不自动加速业务函数计算。字节码还依赖解释器版本和缓存校验规则,第十七篇会详细解释;不要把删除 .pyc 当所有导入问题的默认修复。
8. 从正确的最小包开始,验证启动契约
下面给出与循环依赖不同的正例布局。它是额外的三文件教学实验,需按路径保存;前面的单文件仍是独立验证入口。不要把三个文件内容合在一个文件中运行。
python
# logtool/__init__.py:保留为空,不执行外部工作。python
# logtool/parser.py
def parse(line):
# 固定教学格式:状态码、路径、耗时。
status, path, duration = line.split()
return int(status), path, int(duration)python
# logtool/main.py
from .parser import parse
def main():
status, path, duration_ms = parse("200 /health 0")
print(status, path, duration_ms)
if __name__ == "__main__":
main()在包含 logtool 的目录运行 python -m logtool.main,预期输出 200 /health 0。其中依赖只有入口到解析器,没有解析器反向读取入口状态。测试解析器时可以直接 from logtool.parser import parse,也不会执行入口打印。这个正例的价值不在于多了文件,而是职责与初始化方向清楚;它无需修改全局 PYTHONPATH。
如果必须从任何工作目录启动,应把项目安装到所选运行环境,而不是在每个模块里手动插入项目绝对路径。安装让解释器按环境规则发现包;资源文件仍要用适合的资源访问 API 或配置路径处理。第十四篇会把此布局整理成可安装工具,区分源码目录与安装产物,不在本篇先引入一整套构建工具。
把一个模块既当脚本直接运行,又在同一进程按包名称导入,也可能造成两套身份。入口以 __main__ 存在,正常导入按完整模块名存在;其中定义的类、单例和全局注册表可能分开。为了避免状态分裂,入口应尽量薄,把可复用业务逻辑放在稳定模块名下。不是“所有文件都加入口保护”就能完全解决身份问题。
依赖图可以按层理解:基础解析与数据模型不依赖启动配置,服务逻辑依赖基础层,入口负责组合和启动。需要共享设置时,通过显式参数或专门配置模块提供,避免底层通过导入入口获取状态。导入循环常是职责方向混乱的症状,重构时应修正结构,而不是只把报错那行移动到另一个位置。
最后验证两种动作:新进程中导入目标模块,以及按记录的命令启动应用。前者检查导入契约,后者检查入口和配置;缓存会隐藏部分初始化问题,所以不要只在已经导入过的交互会话中反复尝试。最小实验从新进程开始,也让别人不需要知道你之前在终端执行过什么。
如果团队提供命令行工具,启动契约应记录环境、安装方式和完整模块入口。让用户从任意目录都执行一个裸脚本,再由脚本猜测项目根目录,通常比显式安装和入口更难维护。必要配置可以通过参数或环境提供,错误时说明缺少什么;不要在导入过程中遍历磁盘寻找可能的文件。可靠的发现机制有明确范围,也能被最小实验验证。
模块划分最终服务于可理解的依赖,而不是追求文件数量。只有几十行的独立脚本不必马上拆成十个层级;出现复用、测试边界和资源生命周期需求时再建立包结构。每次拆分都验证新进程导入与实际入口,并检查是否新增顶层副作用。这样才能让“代码组织更清楚”成为可观察结果,而不是目录看起来更复杂。
9. 面试与延伸
import 是否每次执行文件? 正常缓存命中不会重复初始化,但需限定同一解释器和同一完整模块名;重新加载、缓存操作和不同入口会改变行为。
循环导入为什么看到半初始化模块? 模块在执行代码前就登记缓存,避免无限重复加载;另一个模块读取尚未定义的属性就失败。缓存解决身份与递归,不能替你完成初始化顺序。
为什么 -m 能修复相对导入? 它按模块身份启动,建立包上下文。相对导入参照包关系,而不是文件系统当前目录。
用同一加载阶段判断同名文件与循环依赖
将故障换成 json.py 遮蔽标准库,第一步就可能定位到错误来源;循环导入则已经找到正确文件,在初始化阶段失败。两者都从完整名和 spec 开始,但修复位置不同:前者调整命名/搜索,后者调整依赖方向。第一篇确认运行环境,第十四篇验证安装来源,只有阶段判定要求时才迁移到对应章节。
增强实验先调用 find_spec 得到 state 的来源路径与 loader(负责创建或执行模块的加载器),再直接用默认文件系统 PathFinder 查找器查同一个包路径,确认它位于 sys.meta_path、给出的来源一致,而且子模块尚未执行。Finder(查找器)给出加载说明,spec(模块规格)携带来源与加载器,loader 执行源码,模块对象进入缓存供后续请求复用;最后两次导入证明模块只执行一次。这是默认文件系统包的观测链,其他导入钩子可以提供不同来源,不能由一个 SourceFileLoader 推断所有模块来自磁盘。查找子模块的 spec 可能导入父包,观察动作也可能产生父包初始化副作用。
原 a 在 token 设置前导入 b,b 再读取 a.token,失败后程序在同一个临时包加入 shared.py,并把两边都改成从 shared 导入 token;重新导入同一个 a,现在 a.token == a.b.token == "ready"。这证明修复了原依赖,而不是另外建立无关正例。图从 a → b → a 改为 a → b → shared 与 a → shared,共享定义不再回指调用者。
程序清理自己重写文件的字节码缓存,防止同秒同尺寸的教学改写误用旧缓存;这不是在生产里全局删 sys.modules 的建议。真实服务应在新进程验证依赖重构,不要把清缓存当循环依赖修复。失败导入的目标会被移除,但已经成功导入的依赖和副作用可能保留,重试不等于回到从未启动的状态。
独立练习:给 shared 新增一个不可变状态值,要求 a、b 用同一来源,不允许 shared 回导入 a/b。验收全新进程中只执行一次共享初始化,双向访问都成功,同时保留 spec.origin 作为来源证据。环境篇负责决定搜索哪些位置,打包篇负责部署这些文件,加载机制不能替代安装与启动验收。与Spring 循环依赖对照时,只比较依赖方向;Python 模块缓存不提供 Bean 早期代理的那套保障。
一句话总结:导入把搜索、初始化与名称绑定连在一起,可靠项目需要明确包身份和依赖方向。
- 模块是有命名空间的对象,导入共享引用不等于自动同步名称。
- 缓存先于代码初始化建立,循环依赖要分析实际读取时点。
- 启动方式、搜索路径和文件遮蔽都影响结果,用来源证据定位而非反复改路径。
参考:模块教程、导入系统、主模块。独立示例已在 Windows x64 的 CPython 3.14.0 和 3.13.7 验证通过。额外的三文件包在完整安装的 3.13.7 下验证:-m logtool.main 正常输出,直接执行 main.py 则产生预期的相对导入错误;不以嵌入版的隔离搜索路径验证常规启动默认行为。