运行Uvicorn启动FastAPI时提示dotenv模块未找到如何解决？

根因分析 #

你报错日志中Uvicorn的加载路径指向系统全局Python环境，并非你项目的虚拟环境，因此无法读取虚拟环境中安装的dotenv依赖。

解决步骤 #

• 第一步：激活项目虚拟环境
  项目根目录下的env为虚拟环境文件夹，根据你的操作系统执行对应激活命令：

  • macOS/Linux：source env/bin/activate
  • Windows PowerShell：.\env\Scripts\Activate.ps1
  • Windows CMD：.\env\Scripts\activate.bat
    激活成功后命令行前缀会出现(env)标识。

• 第二步：校验虚拟环境依赖
  激活虚拟环境后执行以下命令确认环境状态：

  1. 确认使用的是虚拟环境内的pip：
     macOS/Linux执行which pip，Windows执行where pip，返回路径需指向项目env目录下的pip文件
  2. 确认安装的是官方python-dotenv包：
     执行pip list | grep python-dotenv，若无输出则执行pip install python-dotenv安装，注意不要安装名称为dotenv的非官方包
  3. 确认Uvicorn安装在虚拟环境内：
     执行pip list | grep uvicorn，若无输出则执行pip install uvicorn安装

• 第三步：修正.env文件路径（可选，规避后续配置加载失败问题）
  你当前config.py中使用的Path(".")为命令执行目录，切换启动目录时会导致.env文件加载失败，建议修改为基于文件本身的相对路径：

  # config.py 修改内容
  import os
  from pathlib import Path
  from dotenv import load_dotenv
  
  # 层级对应：config.py所在目录是core -> core在backend下 -> backend在项目根目录下
  BASE_DIR = Path(__file__).parent.parent.parent
  env_path = BASE_DIR / ".env"
  load_dotenv(dotenv_path=env_path)
  

• 第四步：重启服务
  保持虚拟环境激活状态，在项目根目录执行原启动命令即可：

  uvicorn backend.main:app --reload
  

快捷启动方式 #

无需提前激活虚拟环境，可直接调用虚拟环境内的Uvicorn可执行文件启动：

• macOS/Linux：./env/bin/uvicorn backend.main:app --reload
• Windows：.\env\Scripts\uvicorn.exe backend.main:app --reload

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