Python子目录嵌套导入提示No module named 'subfolder'如何解决

报错原因 #

该问题由Python模块导入的搜索路径规则导致：

• 项目入口为rootfile.py时，Python会自动将root目录加入模块搜索路径sys.path，此时folder是可被识别的二级包，全路径导入逻辑正常。
• 在file.py中直接写from subfolder.subfile import subfoo时，Python会将subfolder当做顶级包到sys.path中搜索，但subfolder是folder的子包，默认不在搜索路径范围内，因此抛出模块未找到错误。
• 此前添加sys.path失效大概率是使用了相对路径，会随运行脚本时的工作目录变化失效，没有正确将folder目录加入搜索路径。

可行解决方案 #

方案1：使用相对导入（推荐，符合Python包规范） #

直接在file.py中使用包相对导入写法：

from .subfolder.subfile import subfoo

注意事项：

• 该写法要求整个项目按包规范运行，不要直接单独执行file.py，通过root目录下的rootfile.py作为入口启动即可正常运行。
• 如果需要单独调试file.py，在root目录下执行如下命令即可：

python -m folder.file

方案2：正确添加搜索路径使用绝对导入 #

如果一定要用from subfolder.subfile import subfoo的写法，需要在导入前将folder目录的绝对路径加入sys.path，避免相对路径的动态变化问题：

import sys
from pathlib import Path
# 取当前file.py所在的folder目录的绝对路径加入搜索路径
sys.path.append(str(Path(__file__).parent.resolve()))

from subfolder.subfile import subfoo

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