Uvicorn导入失败主因是Python解释器路径或环境错配。需先区分import报错与命令行执行失败：前者查sys.path、Python/pip环境一致性及版本兼容性；后者查PATH配置或改用python -m uvicorn。

Uvicorn 导入失败，八成不是没装，而是 Python 解释器压根没在找对的地方。 直接看 import uvicorn 报错还是 uvicorn main:app 报错，两者根源完全不同。

运行 uvicorn 命令提示“不是内部或外部命令”

这是 shell 找不到可执行文件，和 Python 模块无关。

• 先确认安装是否生效：pip show uvicorn —— 有输出才说明装进当前环境了
• Windows 用户重点查 PATH：确保 Python\Scripts（比如 C:\Python312\Scripts）已加入系统环境变量
• Mac/Linux 用户检查 ~/.local/bin 是否在 $PATH 里，尤其是用 pip install --user uvicorn 时
• 懒人临时方案：不用命令行，直接跑 python -m uvicorn main:app，绕过 PATH 依赖

import uvicorn 报 ModuleNotFoundError: No module named 'uvicorn'

解释器在 sys.path 里翻遍了都没找到模块，常见于版本错配或环境错位。

Uvicorn 0.52.1

Uvicorn 0.52.1 是 Python ASGI Web 服务器，提供异步应用服务及 WebSocket 支持，常用于 FastAPI、Starlette 等应用的开发和部署。本下载为官方 PyPI 通用 wheel 包，可使用 pip 安装，并由包管理器处理所需依赖。

下载

• 检查 Python 版本是否匹配：例如用 Python 3.7 装了 uvicorn==0.27.0（只支持 3.8+），就会“假装装成功”，实则没核心文件
• 确认 pip 和 python 是同一套环境：which python 和 which pip（Mac/Linux）或 where python / where pip（Windows）路径必须一致
• PyCharm 用户务必核对右下角解释器配置——它可能悄悄用了系统 Python，而你 pip install 的是虚拟环境里的
• 重装时加 --force-reinstall --no-deps 清掉缓存残留，再单独装依赖：pip install click h11 typing-extensions

uvicorn main:app 启动时报 ImportError 或 ModuleNotFoundError

Uvicorn 能运行，但找不到你的应用对象，本质是 Python 导入路径问题。

• 工作目录必须是 main.py 所在目录，否则 uvicorn api.main:app 会因相对路径失效
• 子包结构下必须有 __init__.py（哪怕空文件），否则 api/main.py 不会被识别为 api.main 模块
• 文件名别和标准库冲突：比如叫 json.py 或 http.py，会导致导入时优先加载本地文件而非内置模块
• 检查变量名拼写：uvicorn main:app 要求 main.py 里真有 app = FastAPI() 这行，不能是 application、fastapi_app 或缩写成 a

最常被忽略的一点：Uvicorn 的模块查找逻辑完全复用 Python 的 importlib.import_module，它不关心你项目多漂亮，只认 sys.path + 文件结构 + 变量名。调不通时，先 python -c "import sys; print('\n'.join(sys.path))" 看路径，比瞎试快十倍。