同级模块导入报错：ModuleNotFoundError: No module named 'mod2'

问题场景 #

目录结构：

root
├─mod1
│  ├─script1.py
│  └─__init__.py
└─mod2
   ├─script2.py
   └─__init__.py

执行命令：

python mod1/script1.py

报错信息：

ModuleNotFoundError: No module named 'mod2'

已知信息：

• Python 3.10.7 64位版本
• 所有模块目录均包含__init__.py文件
• Pylance可识别mod2，但运行时导入失败

解决方案 #

方法1：在脚本中手动添加root路径到模块搜索列表 #

在script1.py开头加入以下代码，将root目录加入Python的模块搜索路径：

import sys
import os

# 获取root目录的绝对路径
root_path = os.path.dirname(os.path.dirname(os.path.abspath(__file__)))
sys.path.append(root_path)

# 正常导入mod2
import mod2

方法2：切换到root目录以模块方式运行脚本 #

先切换到root目录，再用-m参数以模块形式执行脚本：

cd /path/to/root
python -m mod1.script1

这种方式会自动将root目录纳入模块搜索路径，符合Python包导入的规范。

方法3：设置PYTHONPATH环境变量 #

通过环境变量将root目录添加到Python的模块搜索路径中：

• Linux/macOS：

  export PYTHONPATH="/path/to/root:$PYTHONPATH"
  

• Windows（CMD）：

  set PYTHONPATH=C:\path\to\root;%PYTHONPATH%
  

• Windows（PowerShell）：

  $env:PYTHONPATH = "C:\path\to\root;$env:PYTHONPATH"
  

设置后直接执行python mod1/script1.py即可正常导入mod2。

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