Python项目运行main.py与pytest时交替出现ModuleNotFoundError如何解决

该报错本质是Python模块搜索路径sys.path不匹配导致的：

• 直接执行python src/main.py时，Python会自动把src目录加入sys.path，因此可以直接识别tools模块
• 执行pytest时，默认会把命令执行的根目录（即project目录）加入sys.path，仅能识别src这个顶层包，无法直接找到tools模块

方案1：将项目配置为标准Python包（长期最优） #

1. 在project根目录新建pyproject.toml配置文件，填入基础包配置：

[build-system]
requires = ["setuptools>=61.0"]
build-backend = "setuptools.build_meta"

[project]
name = "your-project-name"
version = "0.1.0"
packages = ["src"]

2. 在project根目录执行可编辑安装：

pip install -e .

3. 统一所有导入语句为从顶层包导入的格式：

# main.py、test_main.py 都用该导入写法
from src.tools.tool_a import generate_file

配置完成后，无论是直接运行主程序还是执行pytest都可以正常识别模块，也符合Python项目的规范标准。

方案2：配置pytest搜索路径（零代码改动） #

如果不想修改项目结构，仅需调整pytest的路径匹配规则即可：

1. 在project根目录新建pytest.ini配置文件，写入以下内容：

[pytest]
pythonpath = src

2. 保留原有导入写法不变：

# main.py 无需修改
from tools.tool_a import generate_file

该配置会让pytest运行时自动把src目录加入搜索路径，无需改动原有业务代码即可兼容两种运行场景。

方案3：使用模块方式运行主程序 #

无需新增配置文件，仅调整主程序的运行命令：

1. 统一导入语句为带src前缀的写法：

from src.tools.tool_a import generate_file

2. 运行主程序时不要直接执行文件，改用-m参数以模块方式运行：

# 在project根目录执行
python -m src.main

该方式会让Python自动把project根目录加入sys.path，和pytest的默认搜索路径保持一致。

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