VSCode/PyCharm运行Python项目遇ModuleNotFoundError如何解决？

问题场景 #

项目目录结构：

PythonAnalyticalProject/
├── sales_analysis/
│   ├── __init__.py
│   ├── cli.py
│   ├── constants.py
│   ├── db.py
│   ├── sales_analysis.py   (contains main)
├── images/
│   ├── image1.png
│   └── image2.png
├── setup.py
└── requirements.txt

已完成操作：

• 安装requirements.txt中的依赖
• 将PythonAnalyticalProject目录添加至PYTHONPATH

运行sales_analysis.py时触发错误：

ModuleNotFoundError: No module named 'sales_analysis.cli'; 'sales_analysis' is not a package

错误来自sales_analysis.py中的导入语句：

from sales_analysis.cli import user_continue

解决方法 #

1. 使用模块方式运行（推荐） #

直接运行包内的模块文件会导致Python把sales_analysis/目录当作当前路径，无法识别其为顶层包。从项目根目录执行以下命令：

python -m sales_analysis.sales_analysis

这种方式会让Python以包的形式加载模块，正确识别导入路径。

2. 调整IDE运行配置 #

确保VSCode/PyCharm的运行配置将工作目录设为项目根目录（PythonAnalyticalProject/）：

• VSCode：编辑.vscode/launch.json，将cwd字段设置为"${workspaceFolder}"
• PyCharm：在运行配置窗口中，修改"Working directory"为项目根路径

3. 改用相对导入（仅临时方案） #

如果必须直接运行sales_analysis.py，可以将导入语句改为相对导入：

from .cli import user_continue

但这种方式下，模块无法单独运行（直接运行会触发ImportError: attempted relative import with no known parent package），仅适合作为包的一部分通过-m命令运行。

4. 验证PYTHONPATH有效性 #

确认项目根目录已正确加入PYTHONPATH，在Python交互环境中执行：

import sys
print(sys.path)

如果未找到PythonAnalyticalProject路径，手动添加：

• Linux/macOS：终端执行export PYTHONPATH="/path/to/PythonAnalyticalProject:$PYTHONPATH"
• Windows：命令行执行set PYTHONPATH=C:\path\to\PythonAnalyticalProject;%PYTHONPATH%

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