Python项目使用pytest时模块导入失败问题求助

项目结构 #

root
| src
| | __init__.py
| | bsp.py
| | helpers.py
| test
| | __init__.py
| | test_helpers.py

两个__init__.py文件均为空。

代码示例 #

src/bsp.py #

class BSP:
    # some class stuff

src/helpers.py #

from bsp import BSP

def func(x: BSP) -> BSP:
    return x

test/test_helpers.py #

from src.helpers import func
from src.bsp import BSP
from unittest import TestCase

class TestFunc(TestCase):
    def test_func(self):
        x = BSP()
        assert func(x) == x

问题现象 #

在root目录下运行pytest时触发导入错误：

File "...\root\tests\test_helpers.py", line 1, in <module>
from src.helpers import func
File "...\root\src\helpers.py", line 1, in <module>  
from bsp import BSP
ModuleNotFoundError: No module named 'bsp'

但直接在src目录下运行相关函数一切正常。

已尝试方案 #

• 将src/helpers.py中的from bsp import BSP改为from .bsp import BSP，但会导致src目录内的代码导入失效（比如src/main.py调用func时出错）
• 试过pytest、py -m pytest、unittest、py -m unittest等多种命令运行测试
• 在root目录添加__init__.py，以及在test目录增删__init__.py

解决方法 #

方案1：统一使用绝对导入 #

修改src/helpers.py的导入语句为绝对路径：

from src.bsp import BSP

这样不管是在root目录跑测试，还是在src目录内运行代码，导入逻辑都能正常工作。如果src下有main.py这类入口文件，调用helpers时也用绝对导入：

from src.helpers import func

运行测试时优先用py -m pytest（而非直接pytest），或者先把root目录加入Python路径：

# Windows
set PYTHONPATH=你的root目录路径
# Linux/macOS
export PYTHONPATH=你的root目录路径

方案2：相对导入+规范运行方式 #

保持src/helpers.py的相对导入：

from .bsp import BSP

但运行src目录内的代码时，必须以模块方式启动。比如src/main.py要在root目录下运行：

py -m src.main

不能直接进入src目录执行py main.py。测试时在root目录下用py -m pytest即可，这种方式会让Python把src识别为一个包，相对导入就能正常生效。

方案3：配置pytest的Python路径 #

在root目录下创建pytest.ini文件，内容如下：

[pytest]
pythonpath = .

这个配置会让pytest自动把root目录加入Python搜索路径，此时src/helpers.py里的from bsp import BSP就能被正确识别（因为src在搜索路径中），同时不影响src目录内直接运行代码的逻辑。

问题原因 #

本质是Python模块搜索路径的差异：

• 在src目录运行代码时，sys.path包含src目录，所以能直接找到bsp.py
• 在root目录运行测试时，sys.path只包含root目录，bsp.py在src子目录下，不在搜索路径里，所以from bsp import BSP会报错

内容的提问来源于stack exchange，提问作者Pieter van Beerendonk