Python跨目录导入模块时出现模块未找到、相对导入报错
问题核心根源
Python的导入机制有两个核心规则,是所有报错的触发原因:
- 导入搜索逻辑:Python只会在
sys.path记录的路径列表下,查找可识别的包和模块,不会自动遍历项目的所有子目录 - 相对导入生效前提:相对导入仅在当前文件作为包组成部分被加载时可用,直接作为入口脚本运行时会抛出“无已知父包”错误
结合你的目录结构,之前的报错本质是运行时的路径定位偏差:
- 运行
C.ipynb时,Jupyter内核的默认工作目录是tests/,搜索路径里不包含根包Folder的上级目录,所以找不到同级的folder目录;同时notebook被识别为顶层脚本,没有挂载到包命名空间下,所以相对导入完全失效 - 直接运行
A.py时,Python的工作目录默认是Folder/,搜索路径里没有Folder自身的上级位置,所以无法识别folder为可导入的子包
无需修改sys.path的正规解决方案(优先推荐,符合Python项目规范)
这类方法完全不涉及路径手动修改,适配长期开发和调试需求:
调整运行启动位置,以包为单位加载
Python要求包内的导入操作,必须从根包的上级目录启动运行,不能直接把包内部的文件作为入口脚本直接执行:
- 针对
C.ipynb导入B.py的场景:将Jupyter的启动目录切换到包含Folder文件夹的上级路径,而非从tests/目录启动内核。启动完成后在notebook单元格中写入导入语句即可:
此时Python会自动把当前启动目录加入搜索路径,识别from Folder.folder import BFolder为顶层包,逐层定位到子包下的B.py模块。 - 针对
A.py导入B.py的场景:放弃直接运行python A.py的方式,从Folder的上级目录,以模块调用的方式启动脚本,执行命令为:
此时python -m Folder.AA.py内部可以直接使用绝对导入:from Folder.folder import B
规范运行下的相对导入用法
按照上述方式从根包上级启动后,相对导入的报错会直接消失,可根据代码逻辑灵活使用:
- 在
A.py中导入folder/B.py可以写:from .folder import B - 在
folder目录下的B.py中如果要导入根包下的A.py,可以写:from .. import A
临时调试的sys.path调整方案
如果受限于运行环境,没法切换Jupyter启动路径、也没法调整脚本启动方式,可以在需要导入的文件最开头手动将根包上级目录加入搜索路径,这类操作是开发调试阶段的常用手段:
- 在
C.ipynb的第一个单元格中写入:
路径生效后即可正常执行import sys, pathlib # 定位到根包Folder的上级目录 root_path = pathlib.Path().resolve().parent.parent sys.path.append(str(root_path))from Folder.folder import B导入。 - 在
A.py的最开头写入:
路径生效后即可正常导入import sys, pathlib # 定位到根包Folder的上级目录 root_path = pathlib.Path(__file__).parent.parent.resolve() sys.path.append(str(root_path))folder.B模块。
内容的提问来源于stack exchange,提问作者Owen D
相关产品推荐
相关产品推荐

