Python跨目录模块导入时为什么会出现ModuleNotFoundError？如何解决

Python跨目录模块导入时出现ModuleNotFoundError，本质是解释器在默认的模块搜索路径中没有找到需要导入的目标模块。要彻底解决这个问题，需要先理解Python的模块搜索规则，再针对性调整导入方式或路径配置。

Python模块搜索路径机制

Python解释器导入模块时，会按照固定顺序在以下位置查找目标模块：

• 当前执行脚本所在的目录
• 环境变量PYTHONPATH中配置的目录
• Python安装目录下的标准库目录
• 第三方库的安装目录（如site-packages）

这些路径会被存储在sys.path列表中，我们可以通过代码查看当前解释器的搜索路径：

import sys
# 打印当前模块搜索路径
for path in sys.path:
    print(path)

如果目标模块所在的目录不在sys.path中，导入时就会触发ModuleNotFoundError。

跨目录导入报错的常见场景

假设我们有如下项目结构：

project/
├── main.py
└── utils/
    ├── __init__.py
    └── helper.py

如果我们在main.py中直接执行import helper，就会报错，因为helper.py所在的utils目录不在默认的搜索路径中。再比如从utils/helper.py中导入main.py里的函数，同样会因为路径问题触发报错。

解决跨目录ModuleNotFoundError的方法

方法1：临时修改sys.path

可以在导入模块前，把目标模块所在的目录添加到sys.path中，这种方式适合临时调试使用：

import sys
import os
# 获取当前文件所在目录的父目录，也就是project目录的路径
current_dir = os.path.dirname(os.path.abspath(__file__))
parent_dir = os.path.dirname(current_dir)
# 将父目录添加到搜索路径
sys.path.append(parent_dir)
# 此时可以正常导入utils下的模块
from utils import helper

方法2：规范包结构使用绝对导入

如果项目是一个规范的Python包，可以在每个目录下添加__init__.py文件（Python3.3+支持命名空间包，非必需但建议添加），然后使用绝对导入的方式：

# main.py中导入utils/helper.py里的函数
from utils.helper import xxx_func
# utils/helper.py中导入main.py里的函数（需要保证project是根目录）
from main import yyy_func

这种方式要求执行脚本时，项目根目录在sys.path中，通常直接运行根目录下的main.py就可以满足要求。

方法3：使用相对导入

在同一个包内部的模块之间，可以使用相对导入，避免写绝对路径：

# utils/helper.py中导入同目录下的其他模块
from . import other_module
# 导入上级目录的模块
from .. import main

注意相对导入的模块不能作为顶层脚本直接执行，否则会触发ImportError，只能通过包外的脚本调用执行。

方法4：配置PYTHONPATH环境变量

如果需要长期让解释器识别某个目录，可以把该目录添加到PYTHONPATH环境变量中：

Linux/Mac系统可以在终端执行：

export PYTHONPATH=$PYTHONPATH:/path/to/your/project

Windows系统可以在系统环境变量设置中添加PYTHONPATH变量，值为项目根目录的路径。

注意事项

• 避免循环导入，即A模块导入B模块，B模块又导入A模块，会触发导入错误
• 不要随意修改sys.path的顺序，避免覆盖标准库路径导致其他问题
• 项目部署时如果使用虚拟环境，要确保依赖的目录都在搜索路径中

Python跨目录模块导入ModuleNotFoundErrorsys_path修改时间：2026-06-18 00:33:31