Python包内模块导入报错：ModuleNotFoundError问题求助与原因解析

问题场景 #

目录结构：

├── main.py
└── sub
    ├── sub1.py
    └── sub2.py

sub1.py代码：

def function1():
    return "function 1 result"

sub2.py代码：

import sub1

def function2():
    return f"function 2 result: {sub1.function1()}"

main.py代码：

from sub.sub2 import function2

print(function2())

运行main.py时抛出异常：ModuleNotFoundError: No module named 'sub1'

疑问：main.py能识别sub、sub.sub1和sub.sub2，为何sub1和sub2无法互相识别？

原因分析 #

Python的模块查找依赖sys.path列表，当从main.py启动程序时，sys.path的第一个元素是main.py所在的根目录：

• main.py中使用from sub.sub2 import属于绝对导入，Python会从sys.path的根目录找到sub包，再定位到sub2模块，因此能正常识别。
• 而sub2.py中直接import sub1时，Python会在sys.path里查找名为sub1的模块或包，但根目录下并没有sub1.py，只有sub/sub1.py，因此找不到对应的模块，抛出错误。

解决方案 #

有两种常用修复方式：

1. 绝对导入 #

修改sub2.py的导入语句，明确从sub包导入sub1：

from sub import sub1

def function2():
    return f"function 2 result: {sub1.function1()}"

2. 相对导入 #

利用相对路径导入同级模块，.表示当前模块所在的sub包：

from . import sub1

def function2():
    return f"function 2 result: {sub1.function1()}"

两种方式都能让sub2正确找到sub1模块，运行main.py即可得到预期输出：function 2 result: function 1 result

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