Python项目跨子目录导入模块报错ModuleNotFoundError该如何解决？

项目目录结构 #

photo_analyzer/
│
├── main.py                # 运行照片分析器的主脚本
├── gui/                   # GUI相关文件目录
│   ├── __init__.py        # 包初始化文件
│   ├── app.py             # Tkinter应用类及GUI核心逻辑
│   ├── widgets.py         # 自定义Tkinter组件（按需）
│   ├── styles.py          # GUI样式配置
│   └── resources/         # GUI资源目录（如图标、图片）
│       ├── icon.png       # 应用图标
│       └── ...
│
├── photo_analysis/        # 照片分析相关文件目录
│   ├── __init__.py        # 包初始化文件
│   ├── photo_utils.py     # 照片处理工具函数
│   ├── light_profiles.py  # 照片光效分析函数
│   └── ...

报错信息 #

运行gui/app.py时触发模块找不到错误：

Traceback (most recent call last):
  File "c:\Users\Josh\Documents\PhotoAnalyzer\gui\app.py", line 6, in <module>
    from photo_analysis import photo_utils
ModuleNotFoundError: No module named 'photo_analysis'

已尝试操作 #

• 在gui和photo_analysis目录下添加了空的__init__.py文件
• 执行SET PYTHONPATH="C:\Users\Josh\Documents\PhotoAnalyzer\photo_analysis"设置路径
• 尝试用sys.path手动添加路径，但均无效
• 针对photo_utils.py导入gui/widgets.py的潜在循环依赖问题，已在photo_utils的每个使用widgets的方法内做局部导入，photo_utils自身测试代码可正常运行，但app.py的模块找不到问题仍存在

疑问 #

到底忽略了什么？

1. 修正PYTHONPATH配置 #

你之前把PYTHONPATH指向了photo_analysis目录本身，这是错误的。应该将项目根目录（C:\Users\Josh\Documents\PhotoAnalyzer）加入PYTHONPATH，这样Python才能识别photo_analysis和gui作为子包。

正确的环境变量设置命令：

SET PYTHONPATH="C:\Users\Josh\Documents\PhotoAnalyzer"

或者在app.py开头通过代码动态添加根目录：

import sys
import os
# 获取项目根目录（当前脚本目录的上级目录）
root_dir = os.path.dirname(os.path.dirname(os.path.abspath(__file__)))
sys.path.insert(0, root_dir)

# 之后即可正常导入
from photo_analysis import photo_utils

2. 调整运行脚本的工作目录 #

如果直接在gui目录下运行app.py（比如执行python app.py），Python会将当前gui目录作为默认搜索路径，无法找到上级目录的photo_analysis。建议切换到项目根目录后运行脚本：

cd C:\Users\Josh\Documents\PhotoAnalyzer
python gui/app.py

3. 循环依赖的后续注意 #

你已经用局部导入解决了photo_utils的测试问题，只要photo_utils里对widgets的导入是放在函数内部（而非模块顶层），就不会在app.py导入photo_utils时触发循环加载问题，无需额外调整。

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