Python中如何从顶层目录的其他目录相对导入模块？

项目结构 #

project/ 
    main.py
    package1/
        module1.py
        module2.py
        subpackage1/
            module4.py
    package2/
        module3.py 

初始代码文件 #

main.py #

from package1 import module1

package1/module1.py #

from . import module2
from .subpackage1 import module4

package1/subpackage1/module4.py #

from .. import module2

问题场景 #

从项目顶层目录运行python main.py时一切正常，但在module1.py中添加from ..package2 import module3后，触发错误：

ValueError: attempted relative import beyond top-level package

同时发现以下写法可以正常运行：

package1/module1.py（可行版本） #

from . import module2
from .subpackage1 import module4   # 不加相对导入的点的话这行无法运行
from package2 import module3       # 去掉相对导入就可以正常运行

问题解答 #

为什么相对导入跨包会报错？ #

Python的相对导入是基于当前模块所在的包层级工作的：

• package1是一个顶级包，module1.py在这个包内部，用..会尝试回到package1的上层目录（也就是项目根目录），但根目录默认不是Python识别的“包”（没有__init__.py），所以会判定为“超出顶级包范围”，抛出错误。
• 相对导入的./、../只能在同一个顶级包的内部层级移动，无法直接跨到同级的其他顶级包（比如package2）。

怎么实现跨包导入？ #

1. 优先用绝对导入（推荐）
   当你从项目根目录运行脚本时，根目录会自动加入Python的模块搜索路径sys.path，所以直接写from package2 import module3就能正常导入，这是最简洁且不易出错的方式。

2. 将根目录转为顶级包（不推荐日常使用）
   如果一定要用相对导入语法，需要在project/目录下创建__init__.py，把整个项目变成一个顶级包。此时module1.py里的from ..package2 import module3就能生效，但运行方式必须改变——不能直接在根目录运行python main.py，要从根目录的上层执行：

   cd ..
   python -m project.main
   

   这种方式会让Python把project当作顶级包，package1和package2作为它的子包，..就能正确定位到project包层级，从而导入package2。

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