使用Poetry管理FastAPI项目时pytest遇ModuleNotFoundError求助

核心排查与解决步骤 #

• 确认依赖完整安装
  执行 poetry install --no-root 确保所有主依赖和开发依赖都正确安装到虚拟环境。之后用 poetry run pip list 检查输出中是否存在 fastapi 条目，验证依赖是否真的被安装。

• 检查pyproject.toml的依赖配置
  确保fastapi位于[tool.poetry.dependencies]节点下（而非仅在dev-dependencies），示例配置如下：

  [tool.poetry.dependencies]
  python = "^3.10"
  fastapi = "^0.100.0"
  uvicorn = "^0.23.2"
  
  [tool.poetry.dev-dependencies]
  pytest = "^7.4.0"
  

• 强制绑定Poetry虚拟环境的pytest
  避免调用系统全局pytest，改用 poetry run python -m pytest 命令运行测试，强制使用虚拟环境内的Python解释器执行。也可以用 poetry run which pytest 验证当前调用的pytest是否属于Poetry虚拟环境。

• 修正项目结构与导入配置
  如果项目采用包结构（比如根目录有myapp/核心代码包），需在pyproject.toml中明确声明包路径：

  [tool.poetry]
  packages = [{ include = "myapp" }]
  

  若测试文件在tests/目录，可在该目录添加空的__init__.py文件，帮助pytest识别项目结构。

• 重建Poetry虚拟环境
  若缓存导致依赖异常，执行以下命令彻底重建环境：

  poetry cache clear --all pypi
  poetry env remove python3.x  # 替换为你使用的Python版本
  poetry install
  

快速验证方法 #

进入Poetry shell后，先执行 python -c "import fastapi"：

• 若报错：说明虚拟环境未正确安装fastapi，重点排查依赖安装流程；
• 若成功导入：则问题出在pytest配置或测试文件路径，可聚焦调整测试文件的导入逻辑。

内容的提问来源于stack exchange，提问作者Jenia Be Nice Please