Python虚拟环境下unittest模块测试遇ModuleNotFoundError的解决方法及VSCode导入识别配置

首先，你的问题核心是**Python模块搜索路径（sys.path）**的问题——不管是用python -m unittest还是直接运行测试文件，项目根目录默认不在Python的搜索路径里，导致找不到src或test模块。下面分两部分给出解决方案：

一、虚拟环境下运行unittest测试的正确方式 #

方法1：持久化设置PYTHONPATH（最简单的临时方案） #

每次手动加PYTHONPATH=.太麻烦，可以把它加入虚拟环境的激活脚本：

• Linux/macOS：打开.venv/bin/activate，在末尾添加：

  export PYTHONPATH="$(pwd)"
  

• Windows（PowerShell）：打开.venv/Scripts/Activate.ps1，添加：

  $env:PYTHONPATH = (Get-Location).Path
  

之后激活虚拟环境时，项目根目录会自动加入Python搜索路径，直接运行以下命令就能执行测试：

python -m unittest test.test_my_class.Tester
# 或者批量发现测试文件
python -m unittest discover -s test -p "test_*.py"

方法2：在测试文件中手动添加路径（无需修改环境） #

在test_my_class.py的开头添加这段代码，让Python能找到项目根目录：

import sys
from pathlib import Path

# 获取项目根目录（test目录的父目录）
project_root = Path(__file__).parent.parent
sys.path.append(str(project_root))

# 之后正常导入
from src.my_class import MyClass

这样不管你是用python ./test/test_my_class.py还是python -m unittest，都能正确导入模块。

方法3：将项目安装为开发版包（最规范的长期方案） #

这是Python项目的标准做法，能彻底解决路径问题：

1. 在项目根目录创建pyproject.toml文件，内容如下：

[build-system]
requires = ["setuptools>=61.0"]
build-backend = "setuptools.build_meta"

[project]
name = "my-project"
version = "0.1.0"
packages = ["src"]

2. 在虚拟环境中执行：

pip install -e .

-e表示"可编辑模式"，修改src里的代码会立即生效。之后不管你在哪个目录，都能直接导入src.my_class，运行测试也无需额外配置：

python -m unittest test.test_my_class.Tester

二、让VSCode识别导入不报错 #

步骤1：选择虚拟环境的解释器 #

按下Ctrl+Shift+P（Windows/Linux）或Cmd+Shift+P（macOS），输入Python: Select Interpreter，选择.venv目录下的Python解释器。

步骤2：配置VSCode的Python路径和测试设置 #

在项目根目录创建.vscode/settings.json，添加以下内容：

{
    // 让VSCode识别src目录下的模块
    "python.analysis.extraPaths": ["${workspaceFolder}/src"],
    // 配置unittest测试参数
    "python.testing.unittestArgs": [
        "-v",
        "-s",
        "./test",
        "-p",
        "test_*.py"
    ],
    // 禁用pytest（如果不需要），启用unittest
    "python.testing.pytestEnabled": false,
    "python.testing.unittestEnabled": true
}

保存后，VSCode的语言服务就不会再报ModuleNotFoundError，而且你可以在左侧"测试"面板直接运行所有测试用例。

内容的提问来源于stack exchange，提问作者André Rosa