Pytest执行路径异常：PyCharm运行正常但命令行报ModuleNotFoundError

问题原因 #

PyCharm会自动将项目根目录（包含Common和Services的目录）加入Python模块搜索路径sys.path，因此能正常导入Common模块；但命令行执行python -m pytest时，该路径未被自动添加，导致Python无法找到Common模块。

解决方案 #

1. 临时设置PYTHONPATH环境变量

执行pytest前，将项目根目录添加到PYTHONPATH：

• Linux/macOS：

  export PYTHONPATH="/path/to/your/project-root:$PYTHONPATH"
  python -m pytest
  

• Windows（CMD）：

  set PYTHONPATH=C:\path\to\your\project-root;%PYTHONPATH%
  python -m pytest
  

• Windows（PowerShell）：

  $env:PYTHONPATH = "C:\path\to\your\project-root;$env:PYTHONPATH"
  python -m pytest
  

注意：将/path/to/your/project-root替换为实际包含Common文件夹的目录路径。

2. 在代码中手动添加路径

在测试文件（如test1.py）或源码文件（如helper1.py）开头添加以下代码，强制将项目根目录加入搜索路径：

import sys
import os

# 以test1.py为例，从当前文件路径向上回溯3级到项目根目录
project_root = os.path.abspath(os.path.join(os.path.dirname(__file__), '../../../../'))
sys.path.append(project_root)

根据实际文件层级调整../../../../的数量，确保project_root指向包含Common的目录。

3. 使用pytest的conftest.py配置

在项目根目录创建conftest.py文件，添加以下内容：

import sys
import os

# 将项目根目录加入搜索路径最前端
sys.path.insert(0, os.path.abspath(os.path.dirname(__file__)))

pytest执行时会自动加载该文件，无需手动设置路径。

4. 将项目安装为可编辑模块（长期项目推荐）

在项目根目录创建setup.py文件：

from setuptools import setup, find_packages

setup(
    name="your-project-name",
    version="0.1",
    packages=find_packages(),
)

执行以下命令将项目安装为可编辑模式：

pip install -e .

安装后，Python会自动识别项目模块，无论在哪执行pytest都能正常导入Common。

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