启动FastAPI项目时uvicorn提示缺失uvloop>=0.14.0依赖报错如何解决

根本原因 #

你触发报错的核心原因是执行环境不匹配：从报错栈中uvicorn的路径/usr/bin/uvicorn可以确认，你启动服务调用的是系统全局安装的uvicorn，而你之前执行pip安装uvloop时，依赖被安装到了当前激活的venv虚拟环境中，全局uvicorn在全局Python环境中找不到对应的uvloop依赖，因此抛出找不到包的错误。另外你原来的启动命令uvicorn main.py:app --reload写法也存在错误，正确的实例引用格式是[模块名]:[实例名]，不需要加.py后缀。

分步解决方法 #

• 方案1：使用虚拟环境启动（推荐）
  1. 确认虚拟环境已激活（命令行前缀有(venv)标识）
  2. 执行命令统一安装虚拟环境内的依赖：

  pip install fastapi uvicorn uvloop
  

  3. 用虚拟环境的Python解释器调用uvicorn启动，避免调用全局uvicorn：

  python -m uvicorn main:app --reload
  

• 方案2：给全局uvicorn补全依赖
  如果不需要用虚拟环境，直接给全局Python环境安装缺失依赖即可：

  sudo /usr/bin/pip install "uvloop>=0.14.0"
  

  之后使用修正后的命令启动即可：

  uvicorn main:app --reload
  

• 方案3：临时规避uvloop依赖
  如果你不需要uvloop的性能优化，可以指定uvicorn使用Python标准库的asyncio事件循环，跳过uvloop的依赖检查：

  uvicorn main:app --reload --loop asyncio
  

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