Python相对导入报错疑问：‘attempted relative import beyond top-level package’理解确认

目录结构 #

（所有文件位于project文件夹下）

.
├── folder_1
│   ├── folder_3
│   │   ├── module_3.py
│   │   └── module_4.py
│   └── module_1.py
├── folder_2
│   └── module_2.py
└── script.py

module_3.py 代码 #

# module_3.py
print("Code is currently in module_3.py file")
print("\n File name of module_3.py :",__name__)

from . import module_4
from .. import module_1
from ...folder_2 import module_2

两种运行结果 #

• 执行命令 python3 -m project.folder_1.folder_3.module_3，程序运行成功。
• 执行命令 python3 -m folder_1.folder_3.module_3，抛出错误：

Traceback (most recent call last):
  File "/Library/Developer/CommandLineTools/Library/Frameworks/Python3.framework/Versions/3.9/lib/python3.9/runpy.py", line 197, in _run_module_as_main
    return _run_code(code, main_globals, None,
  File "/Library/Developer/CommandLineTools/Library/Frameworks/Python3.framework/Versions/3.9/lib/python3.9/runpy.py", line 87, in _run_code
    exec(code, run_globals)
  File "/Users/admin/Desktop/remote/project/folder_1/folder_3/module_3.py", line 13, in <module>
    from ...folder_2 import module_2
ImportError: attempted relative import beyond top-level package

疑问解答 #

1. 关于顶级包的理解是否正确？ #

你的理解完全正确。当执行python3 -m project.folder_1.folder_3.module_3时，Python会将project识别为顶级包，此时folder_1和folder_2都是project的子包，相对导入...folder_2可以向上回溯到project层级，顺利找到folder_2。

而执行python3 -m folder_1.folder_3.module_3时，Python会把folder_1当作顶级包，project目录不会被视为包的一部分。此时相对导入...folder_2需要跳出folder_1这个顶级包，违反了Python相对导入不能超出当前顶级包的规则，因此触发错误。

2. 是否最好带上最顶层父文件夹名称？ #

是的，对于包含多子包的项目，以最顶层包名（比如这里的project）作为模块运行的起点是更稳妥的做法。这样能明确告知Python项目的顶级包边界，避免相对导入出现路径混乱，同时也符合Python项目的模块化规范。

3. 若理解有误，为何无法访问folder_2？ #

你的理解没有错误，无法访问folder_2的核心原因就是第二种运行方式下，Python仅将folder_1识别为顶级包，folder_2不在这个顶级包的范围内，相对导入无法跨越到包外部的目录。

内容的提问来源于stack exchange，提问作者user10089194