Python项目跨子目录导入模块遇ModuleNotFoundError求助

项目目录结构：

main_directory
  main.py
  drivers
    __init__.py
    xyz.py
  utils
    __init__.py
    connect.py

尝试在xyz.py中导入connect.py：

from utils import connect as dc

报错：

ModuleNotFoundError: No module named 'utils'

疑问：不理解为何需要设置路径/目录，认为导入应该自动生效。

方法1：使用相对导入 #

修改xyz.py中的导入语句为相对路径形式（drivers和utils是同级目录）：

from ..utils import connect as dc

注意：这种方式下不能直接运行xyz.py，必须以项目根目录main_directory作为顶层包启动，比如在main_directory下执行：

python -m drivers.xyz

或者通过main.py导入drivers.xyz后运行main.py。

方法2：手动添加项目根目录到搜索路径 #

在xyz.py最开头添加代码，把项目根目录（main_directory）加入Python模块搜索路径：

import sys
import os
# 获取当前文件的父目录的父目录，即main_directory
sys.path.append(os.path.dirname(os.path.dirname(os.path.abspath(__file__))))

# 之后执行导入
from utils import connect as dc

修改后直接运行xyz.py也能正常找到utils包。

方法3：以项目根目录为入口运行 #

始终通过main.py作为项目入口，在main.py中导入drivers.xyz：

from drivers import xyz

然后在main_directory下执行：

python main.py

此时Python会自动把main_directory加入搜索路径，xyz.py中的from utils import connect as dc就能正常生效。

Python的模块搜索路径默认包含：

• 当前执行脚本所在的目录（不是导入脚本的目录）
• Python自带标准库目录
• 第三方库安装目录

如果直接运行drivers/xyz.py，当前执行目录是drivers，main_directory不在搜索路径里，自然找不到上层的utils包。只有当项目根目录在搜索路径中时，Python才能识别utils为顶层包，导入才会自动生效。

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