Python跨子目录导入遇阻：ModuleNotFoundError问题求助

核心问题根源 #

1. 模块搜索路径缺失：Python默认仅将当前运行脚本所在目录加入搜索路径，main.py在src/下，无法直接找到上层的utils/目录。
2. 相对导入的使用限制：直接运行main.py时，它被视为顶层脚本而非包的子模块，此时使用..utils.var这类相对导入会触发错误。

具体解决方法 #

方法一：以包模块方式运行（推荐） #

• 第一步：在app/目录下创建空的__init__.py文件（Python3.3+可省略，但添加后更符合包规范）。
• 第二步：从包含app的父目录（而非src/目录），用模块启动命令运行main.py：

  python -m app.src.main
  

• 此时在main.py中可使用两种导入方式：
  • 绝对导入：

    from app.utils.var import 类名1, 类名2
    

  • 相对导入：

    from ..utils.var import 类名1, 类名2
    

方法二：手动添加搜索路径（临时测试用） #

在main.py的最顶部添加代码，将app/目录加入Python的模块搜索路径：

import sys
from pathlib import Path

# 获取app目录的绝对路径
app_dir = Path(__file__).parent.parent
sys.path.append(str(app_dir))

# 正常导入
from utils.var import 类名1, 类名2

注意：此方法仅适合快速测试，正式项目不推荐，路径易受运行位置影响。

方法三：设置PYTHONPATH环境变量（全局生效） #

通过环境变量将app/目录加入Python的全局搜索路径：

• Linux/macOS终端：

  export PYTHONPATH="/你的app目录绝对路径:$PYTHONPATH"
  

• Windows CMD：

  set PYTHONPATH=C:\你的app目录绝对路径;%PYTHONPATH%
  

• Windows PowerShell：

  $env:PYTHONPATH = "C:\你的app目录绝对路径;$env:PYTHONPATH"
  

设置完成后，无论从哪个目录运行main.py，都可直接使用from utils.var import ...导入类。

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