Python跨应用相对导入报错：Attempted relative import beyond top-level package

为什么会报错？ #

这个问题我帮不少开发者踩过坑，核心原因是Python对「顶层包」的识别逻辑和你预期的不一样～当你直接运行app2/models.py（比如敲python app2/models.py）时，Python会把app2所在的目录当成顶层包——这时候..就指向了顶层包之外的project目录，自然就抛出「超出顶层包」的错误了。简单说：你以为顶层包是project，但Python此时认的是app2，路径自然对不上。

几种靠谱的解决方案 #

1. 绝对导入+把project当作顶层包运行（最推荐） #

首先给你的项目补上__init__.py文件（Python3.3+允许无init文件，但加上更规范，能避免不少奇怪问题），结构变成这样：

project/
├── __init__.py
├── app1/
│   ├── __init__.py
│   └── models.py
└── app2/
    ├── __init__.py
    └── models.py

然后在app2/models.py里改用绝对导入：

from project.app1.models import Model

# 测试一下
if __name__ == "__main__":
    model = Model()

接下来切换到project的上级目录（也就是包含project的那个文件夹），运行命令：

python -m project.app2.models

这时候Python会把project识别为顶层包，绝对导入就能正常工作了。

2. 用入口脚本启动，避免直接运行子模块 #

如果你的项目有统一入口（比如project/main.py），可以从这里导入app2的模块，此时相对导入就能正常用：

在project/main.py里写：

from app2.models import test_import
test_import()

然后在app2/models.py里继续用相对导入：

from ..app1.models import Model

def test_import():
    model = Model()
    print("成功导入Model类啦！")

同样在project的上级目录运行：

python -m project.main

这时Python会把project作为顶层包，..app1的相对路径就能被正确解析。

3. 临时添加project路径到sys.path（应急用，不推荐） #

如果只是临时测试，不想改结构或运行方式，可以在app2/models.py开头加一段代码，手动把project目录加入Python的模块搜索路径：

import sys
from pathlib import Path

# 获取project目录的绝对路径
project_dir = Path(__file__).parent.parent
sys.path.append(str(project_dir))

# 现在可以直接导入app1的模块
from app1.models import Model

这种方法的缺点是依赖脚本的位置，部署时容易出问题，只建议临时救急。

总结 #

相对导入是为包内部模块之间的引用设计的，前提是整个project被当作一个包来加载。只要你避免直接运行子模块，而是从顶层包的入口启动，或者用绝对导入指定顶层包，这个问题就能轻松解决啦～

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