Python导入错误排查：ModuleNotFoundError及测试执行方案咨询

阿华AIGC实验室

2026-5-21

问题原因分析

当你单独运行source/lib/stats.py时，Python会自动把当前脚本所在的目录（也就是source/lib）添加到sys.path里，所以import utils能找到同目录下的utils.py。

但当你通过test/lib/test_stats.py导入lib.stats时，你的PYTHONPATH设为source，此时sys.path里只有source目录。这时候stats.py里的import utils会去source目录下找utils.py，而不是source/lib，自然就找不到了——这就是你遇到ModuleNotFoundError的核心原因：你假设了两种运行场景下的模块搜索路径一致，但实际上它们是不同的。

针对当前目录结构的解决方法

方法1：修正`stats.py`的导入语句（推荐）

把stats.py里的import utils改成相对导入或者绝对导入：

相对导入（推荐，适合包内模块间引用）：
```
from . import utils
```
绝对导入（基于PYTHONPATH=source的配置）：
```
import lib.utils as utils
```

修改后，在project目录下执行：

PYTHONPATH=source pytest

就能正常运行测试了。

方法2：调整`PYTHONPATH`（不推荐，灵活性差）

如果你不想修改代码，可以把PYTHONPATH设为source/lib，但这样会导致import lib.stats失效，因为lib目录不在sys.path里了，所以这种方法得不偿失。

关于pip开发模式、tox的必要性

这些方法不是解决当前问题的必要手段，它们是更工程化的解决方案，但你的问题本质是导入语句的错误假设：你用了脚本级的导入方式（import utils）来处理包级的模块引用。

pip开发模式（pip install -e .）：会把你的source目录（假设你有setup.py或pyproject.toml）注册到Python的site-packages里，这样lib包会被全局识别，不管在哪运行都能正常导入。这是长期维护项目的推荐方式，但不是必须的——修正导入语句就能解决当前问题。
tox：是用来管理多环境测试的工具，它会帮你自动处理环境变量和依赖，但同样，它不是解决这个导入错误的必要条件，只是让测试流程更规范。

总结一下：当前的核心问题是模块导入路径的错误，修正stats.py里的导入语句就能解决，pip开发模式和tox是锦上添花的工具，不是必须的。

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