解决pytest运行时sys.path引发的src模块导入失败问题

项目目录结构 #

<root>
+-- src
|    +- module1.py
|    |
|    +- module2.py
|    |
|    + __init__.py
|
+-- test
     +- test1
     |    +- test1.py
     |    |
     |    + __init__.py
     |
     +- test2.py
     |
     +- __init__.py

相关文件内容 #

• test/__init__.py 代码：

  import sys
  sys.path.append(".")
  

• test/test1/__init__.py 代码：

  import sys
  sys.path.append("..")
  

• test/test1/test1.py 和 test/test2.py 均包含导入语句：

  from src import module1, module2
  

问题现象 #

在项目根目录执行 pytest test1 时一切正常，但执行 pytest 时，test2 会因无法解析 src 模块而在导入语句处失败。

已尝试的无效操作：

• 修改 test/__init__.py，将 ".." 添加到 sys.path 中
• 改用相对导入语句 from ..src import module1, module2

方案1：将项目安装为可编辑模式（推荐） #

在项目根目录执行以下命令：

pip install -e .

此操作会把 src 注册为系统可识别的 Python 包，无论从哪个目录运行 pytest，都能直接导入 src 下的模块，无需手动修改 sys.path，这是最符合 Python 包规范的做法。

方案2：通过 conftest.py 统一配置路径 #

在项目根目录创建 conftest.py 文件，写入以下代码：

import sys
from pathlib import Path

# 获取项目根目录的绝对路径
root_path = Path(__file__).absolute().parent
sys.path.append(str(root_path))

pytest 会自动加载根目录下的 conftest.py，将根目录加入 sys.path，这样所有测试文件中的 from src import ... 语句都能正常解析，不管是执行 pytest 还是 pytest test1 都能生效。

方案3：在测试文件中动态添加根目录（不推荐） #

如果暂时不想用上面两种规范方案，可以在每个测试文件开头添加路径配置代码：

import sys
from pathlib import Path

# 根据测试文件位置计算根目录：test2.py 需取父级的父级，test1.py 需取父级的父级的父级
root_dir = Path(__file__).resolve().parent.parent  # 针对 test2.py
# root_dir = Path(__file__).resolve().parent.parent.parent  # 针对 test1.py
sys.path.append(str(root_dir))

from src import module1, module2

这种方法需要根据测试文件的层级调整路径计算逻辑，维护成本较高，仅适合临时场景使用。

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