使用python -m pytest运行测试报ModuleNotFoundError: No module named 'sample'错误

API 探路者

2026-9-24

问题原因

pytest 默认不会自动将项目根目录下的 src 文件夹加入 Python 模块搜索路径，而 nose 等其他测试工具默认会自动识别 src 布局的项目结构，将 src 加入搜索路径，因此会出现其他测试工具可正常运行、pytest 找不到 sample 模块的报错。你当前使用的是 Python 社区标准的 src 项目布局，sample 包存放在 src 目录下，pytest 运行时无法扫描到该路径，因此导入模块失败。

解决办法

你可以根据自己的使用场景选择以下任意一种方案解决：

方案1（临时生效，适合单次运行测试）：运行命令前临时设置 PYTHONPATH 环境变量，将 src 加入搜索路径
- Linux/macOS 终端执行：PYTHONPATH=./src python -m pytest
- Windows CMD 执行：set PYTHONPATH=./src && python -m pytest
- Windows PowerShell 执行：$env:PYTHONPATH="./src"; python -m pytest
方案2（永久生效，适配当前项目）：在项目的 pytest 配置文件中添加路径配置，你可以选择修改已有的 setup.cfg 或者 pyproject.toml、tox.ini 文件
如果修改 setup.cfg，添加如下内容：
```
[tool:pytest]
testpaths = tests
pythonpath = src
```
如果修改 pyproject.toml，添加如下内容：
```
[tool.pytest.ini_options]
testpaths = ["tests"]
pythonpath = ["src"]
```
配置完成后直接运行 python -m pytest 即可正常识别 sample 模块。
方案3（全局生效，最规范的处理方式）：使用可编辑模式安装当前项目，执行命令：pip install -e .
安装完成后 sample 包会进入 Python 全局可搜索路径，不管使用什么测试工具都可以直接识别到该模块，同时还可以验证你的项目打包配置是否正确。