Uvicorn报错“ModuleNotFoundError”本质是Python版本与Uvicorn版本不兼容或安装路径错位：需核对python --version与uvicorn官方支持范围，用对应解释器执行pip安装（如python311 -m pip install uvicorn），并确保IDE解释器、运行配置、工作目录一致。
Uvicorn版本和Python解释器不匹配
报错 ModuleNotFoundError: No module named 'uvicorn' 表面是找不到模块，实际八成是版本硬冲突——比如用 Python 3.7 装了 uvicorn==0.27.0，而它只支持 3.8~3.13。pip 安装时可能“成功”，但核心模块压根没生成。
- 查当前 Python 版本：
python --version - 查要装的 uvicorn 支持范围：官方明确写死——
uvicorn 0.27.x→3.8~3.13；0.24.x→3.7~3.12；0.20.x→3.6~3.11 - 降级安装（例如 Python 3.7）：
pip install uvicorn==0.24.0 --force-reinstall - 别信 pip 的 “Successfully installed” —— 装完立刻验证：
python -c "import uvicorn; print(uvicorn.__version__)"
多个Python版本共存时pip装错解释器
Windows 上装了 python311.exe 和 python38.exe，但你敲 pip install uvicorn，结果装到了默认的 python38 下，而运行时用的是 python311，自然 import 失败。
Uvicorn 0.52.1
下载
Uvicorn 0.52.1 是 Python ASGI Web 服务器，提供异步应用服务及 WebSocket 支持，常用于 FastAPI、Starlette 等应用的开发和部署。本下载为官方 PyPI 通用 wheel 包，可使用 pip 安装，并由包管理器处理所需依赖。
- 永远用对应解释器调 pip：
python311 -m pip install uvicorn，而不是裸 pip - Windows 下检查
pip命令绑定哪个 python：where pip，再对比where python - 用
uv管理多版本更省心：uv python install 3.11→uv venv --python 3.11→uv pip install uvicorn，全程路径自动对齐
PyCharm/VS Code 中解释器配置错位
IDE 显示已选 Python 3.11 解释器，但 Run Configuration 里没指定 Module path 或 Working directory 错了，导致运行时实际加载的是系统全局 site-packages 里的旧版 uvicorn。
- PyCharm：File → Settings → Project → Python Interpreter → 确认右上角显示的是你期望的 Python 路径（比如
C:\Users\X\.local\bin\python311.exe） - Run Configuration 的 “Python interpreter” 必须和上面一致，且 “Working directory” 设为
main.py所在目录 - 终端里手动跑一遍：
python311 -m uvicorn main:app --port 8001，如果它能跑通但 IDE 不行，问题就锁定在 IDE 配置
热重载失效+启动报 loop_factory 错误
不是所有版本都兼容新 Python 的 asyncio，默认 uvicorn.run() 或 PyCharm 调试模式下会因 loop_factory 参数被拒绝而崩溃，典型错误是 TypeError: run() got an unexpected keyword argument 'loop_factory'。
- 这不是代码问题，是 uvicorn ≥0.29.x 与 Python 3.12+ 的调试器补丁冲突
- 开发阶段最稳方案：
pip install uvicorn==0.20.0 --force-reinstall - 别在脚本里写
uvicorn.run(..., reload=True)—— 它在 IDE 里基本无效；一律走命令行：uvicorn main:app --reload --port 8001 - 如果必须用 IDE 一键运行，Run Configuration Type 选 “Module”，Module name 填
uvicorn，Parameters 填完整命令
import uvicorn 就会静默失败。先盯死 python -c "import sys; print(sys.executable)" 和 python -c "import sys; print(sys.path)"，再动手。 
