跨文件夹导入模块遇ModuleNotFoundError问题求助

核心原因 #

Python运行时会从当前工作目录和sys.path配置的路径查找模块，VS Code能识别导入是因为有独立的代码分析逻辑，和运行时的Python环境路径不统一，所以会出现编辑器不报错但运行失败的情况。

可行解决方案 #

方案1：动态添加模块路径到sys.path #

如果之前用sys.path.insert失败，大概率是路径写法错误。假设你的文件夹结构是：

项目根目录/
├─ d1/
│  └─ mod1.py
└─ mod2.py

在mod2.py最顶部添加以下代码，动态获取项目根目录并加入路径：

import sys
import os
# 获取当前脚本所在目录（即项目根目录）并加入sys.path
sys.path.insert(0, os.path.dirname(os.path.abspath(__file__)))

之后再执行导入：

from d1.mod1 import mymod
print(mymod())

注意：给d1文件夹添加空的__init__.py文件，让它成为合法的Python包，Python 3.3+虽支持无该文件的命名空间包，但添加后兼容性更好。

方案2：使用相对导入（需按包运行） #

若mod2.py与d1在同一目录下，可改用相对导入语法：

from .d1.mod1 import mymod

但这种写法不能直接运行mod2.py，必须在项目根目录下以包的方式执行：

python -m mod2

方案3：通过环境变量指定模块路径 #

在终端中先配置PYTHONPATH环境变量，再运行脚本：

• Windows终端：

set PYTHONPATH=你的项目根目录绝对路径
python mod2.py

• Linux/macOS终端：

export PYTHONPATH=你的项目根目录绝对路径
python mod2.py

配置后Python会自动从该路径查找模块，无需修改代码。

避坑提示 #

• 不要写死绝对路径，比如sys.path.insert(0, "C:/xxx/项目")，换环境后会失效，用os.path动态获取路径更可靠。
• 确认运行脚本时的当前工作目录，若VS Code终端的当前目录不是项目根目录，也会导致找不到d1模块。

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