如何解决 pip install 安装报错 ModuleNotFoundError: No module named ‘uvicorn’ 问题

Python系列Bug修复PyCharm控制台pip install报错：如何解决 pip install 安装报错 ModuleNotFoundError: No module named ‘uvicorn’ 问题

摘要

在日常开发中，使用 PyCharm 控制台 进行 pip install 安装第三方库时，经常会遇到 ModuleNotFoundError: No module named 'uvicorn' 这样的报错。这个问题不仅出现在新手环境配置时，甚至在老项目迁移、虚拟环境切换或者包冲突时也会频繁触发。

本文将围绕 开发场景、环境说明、常见原因、解决方案及扩展方案 进行超详细讲解，帮助你彻底掌握 pip install 的排坑流程。

---

一、开发场景说明

通常这个异常出现在以下几类场景：

• PyCharm 新建项目后，未配置解释器或未勾选虚拟环境。
• 使用 pip install uvicorn 成功安装，但是运行时报 ModuleNotFoundError。
• 公司内网或学校网络，pip 下载依赖超时或安装不完整。
• 多版本 Python 共存（如同时存在 Python3.8、Python3.11），导致依赖装错解释器。

💡典型报错日志：

Traceback (most recent call last):File "main.py", line 1, in <module>import uvicorn
ModuleNotFoundError: No module named 'uvicorn'

---

二、开发环境

• 系统：macOS 13.5
• Python版本：Python 3.11
• IDE：PyCharm 2025 专业版
• 依赖安装方式：pip install uvicorn

---

三、常见原因分析与解决方案

1. Module 未安装或包名错误

• 检查是否真的安装了包：

  pip show uvicorn
  

• 如果没有结果，说明未安装，需要执行：

  pip install uvicorn
  

• 注意拼写错误，比如 uvicorn 有人写成 uvircon。

---

2. 网络问题，切换国内源

如果下载超时，可以临时指定国内源：

pip install uvicorn -i https://pypi.tuna.tsinghua.edu.cn/simple

配置文件写法（推荐长期使用）：

Linux/macOS → ~/.pip/pip.conf
Windows → C:\Users\xxx\pip\pip.ini

[global]
index-url = https://pypi.tuna.tsinghua.edu.cn/simple

---

3. 忘记 import 或路径错误

即使安装了包，如果写错导入也会报错：

# 正确写法
import uvicorn

---

4. 没有 __init__.py

如果你自己写了一个模块，但忘了加 __init__.py，Python 会识别不到。
解决：在每个自定义包目录下加一个空的 __init__.py。

---

5. 版本冲突 / 依赖不兼容

有时 uvicorn 与某些库版本冲突，比如 fastapi 版本过旧。
可以尝试：

pip install -U uvicorn fastapi

---

6. 包名冲突

如果项目中有一个文件夹叫 uvicorn，Python 可能导入的是你的文件夹而不是第三方库。
解决：重命名自建包，避免与库同名。

---

7. PYTHONPATH 未设置

如果手动写了模块路径但没有添加到环境变量，Python 无法找到。
解决方案：
在 .bashrc 或 .zshrc 中加入：

export PYTHONPATH=$PYTHONPATH:/your/project/path

---

8. 不恰当的相对导入

错误写法：

from . import uvicorn

应改为绝对导入：

import uvicorn

---

9. pip 版本过低

老版本 pip 无法解析新依赖，建议升级：

pip install --upgrade pip

---

10. 额外扩展思路

• 使用 conda 管理环境，避免全局冲突：

  conda create -n fastapi python=3.11
  conda activate fastapi
  pip install uvicorn
  

• 使用 requirements.txt 保证依赖统一：

  fastapi==0.110.0
  uvicorn==0.29.0
  

---

四、问题排查流程（Mermaid流程图）

---

五、总结对比表格

问题原因	解决方案	难度等级
包未安装	pip install uvicorn	⭐
网络问题	换国内源（清华、中科大、阿里源）	⭐⭐
包名冲突	避免与库同名	⭐⭐
版本冲突	pip install -U fastapi uvicorn	⭐⭐⭐
没有 __init__.py	添加空文件	⭐
PYTHONPATH 未设置	设置环境变量	⭐⭐
pip 版本过低	pip install --upgrade pip	⭐

---

六、UML类图示意

---

温馨提示🔔

更多Bug解决方案请查看==>全栈Bug解决方案专栏https://blog.csdn.net/lyzybbs/category_12988910.html

---

作者✍️名片

---