如何解决Python特定项目结构下出现的ModuleNotFoundError报错

报错原因 #

运行单个测试脚本时，Python默认只会将当前运行的脚本所在的目录（即tests/data_mining/）加入模块搜索路径sys.path，你的项目根目录Project2.1不在搜索路径中，因此无法找到project2模块。

解决方法 #

方法1：使用-m参数以模块方式运行（最推荐，无需修改代码） #

在Project2.1根目录下执行以下命令即可：

python3 -m tests.data_mining.test_process

-m参数会让Python将当前工作目录自动加入模块搜索路径，同时以模块的形式加载测试文件，不需要调整代码即可正常导入project2。

方法2：临时将项目根目录加入搜索路径 #

在test_process.py文件最开头添加以下代码，手动把项目根目录加到sys.path中：

import sys
from pathlib import Path
# 向上回溯3级目录得到项目根目录：test_process.py → tests/data_mining/ → tests/ → Project2.1/
sys.path.append(str(Path(__file__).parent.parent.parent))

添加完成后再直接运行测试脚本即可正常导入。

方法3：配置PYTHONPATH环境变量（临时生效） #

运行测试前先执行命令将当前目录加入环境变量：

• Linux/macOS 终端：

export PYTHONPATH=$(pwd)
python3 tests/data_mining/test_process.py

• Windows PowerShell：

$env:PYTHONPATH = $(pwd)
python3 tests/data_mining/test_process.py

方法4：开发模式安装项目（长期开发推荐） #

在项目根目录Project2.1下添加pyproject.toml配置文件，然后执行pip install -e .将项目安装到Python环境中，后续无论在哪运行都可以正常导入project2模块。

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