Python跨目录导入类提示No module named main的原因及解决方法

报错原因 #

• Python导入模块时只会搜索sys.path列表中包含的路径，默认包含当前脚本的执行目录、Python内置库路径、第三方库安装路径。如果main文件夹的上级目录不在sys.path的搜索范围内，Python就无法识别main为可导入的包，就会报"No module named main"的错误。
• 低版本Python（3.3以下）或者部分运行环境，需要目录下存在空的__init__.py文件，才会将该目录识别为Python包，缺少这个文件也会导致导入失败。
• 如果你执行脚本的工作目录已经进入了main文件夹内部，导入路径还带main前缀也会触发该错误。

修复步骤 #

第一步：补全包标识文件 #

首先在所有需要作为包导入的目录下，新建空的__init__.py文件，调整后的目录结构如下：

main
├── __init__.py
├── folder 1
│   ├── __init__.py
│   └── file1.py
└── folder 2
    ├── __init__.py
    └── file2.py

Python 3.3+版本虽然支持无__init__.py的命名空间包，但添加该文件可以兼容所有运行环境，避免兼容性问题。

第二步：选择适配的导入方案 #

方案1：临时添加搜索路径（适合单项目调试，无侵入性）

在执行导入操作的脚本开头，先将main文件夹的上级目录添加到sys.path中，示例代码如下：

import sys
import os
# 若当前执行的脚本和main文件夹处于同一级目录，可直接用相对路径获取上级目录
sys.path.append(os.path.dirname(os.path.abspath(__file__)))
# 也可以直接写main上级目录的绝对路径，比如 sys.path.append("/home/user/my_project")

添加完成后再执行from main.folder1.file1 import class1即可正常导入。

方案2：以模块方式运行脚本

执行脚本时切换到main文件夹的上级目录，使用-m参数以模块形式启动脚本，比如你要运行folder2下的file2.py，执行命令如下：

python -m main.folder2.file2

这种方式会自动将当前工作目录加入sys.path，无需修改代码就能正常识别main包。

方案3：直接简化导入路径（仅适合固定在main目录内运行的场景）

如果你执行脚本的工作目录固定在main文件夹内部，直接去掉导入路径里的main前缀即可：

from folder1.file1 import class1

注意：不推荐将路径永久添加到系统PYTHONPATH环境变量的方案，会影响其他项目的导入逻辑，降低项目的可迁移性。

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