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

【Python系列Bug修复PyCharm控制台pip install报错】如何解决pip安装报错ModuleNotFoundError: No module named 'websockets'问题

摘要

在日常Python开发中，使用 pip install 安装依赖包是最常见的操作之一。但不少同学在 PyCharm控制台 或命令行执行 pip install websockets 后，依然在运行项目时报错：

ModuleNotFoundError: No module named 'websockets'

本文将从 环境配置、常见场景、版本冲突、路径设置、pip源问题 等多个角度，逐步分析并给出详细解决方案。

文章目录

• [【Python系列Bug修复PyCharm控制台pip install报错】如何解决pip安装报错ModuleNotFoundError: No module named 'websockets'问题](#【Python系列Bug修复PyCharm控制台pip install报错】如何解决pip安装报错ModuleNotFoundError: No module named ‘websockets’问题)
• • 摘要
  • 一、开发环境说明
  • 二、常见错误场景复盘
  • 三、错误原因与解决方案详解
  • • [1. 模块未安装或包名错误](#1. 模块未安装或包名错误)
    • [2. pip 版本过旧](#2. pip 版本过旧)
    • [3. 网络问题（国内用户常见）](#3. 网络问题（国内用户常见）)
    • [4. 环境与解释器不一致](#4. 环境与解释器不一致)
    • [5. 忘记 `import` 或导错包](#5. 忘记 import 或导错包)
    • [6. 缺少 `init.py` 文件](#6. 缺少 __init__.py 文件)
    • [7. 包版本不兼容](#7. 包版本不兼容)
    • [8. 自定义包名冲突](#8. 自定义包名冲突)
    • [9. PYTHONPATH 未设置](#9. PYTHONPATH 未设置)
    • [10. 相对导入错误](#10. 相对导入错误)
  • 四、解决流程可视化
  • 五、常见问题对照表
  • 六、总结与扩展思路

---

一、开发环境说明

在复现问题的过程中，开发环境如下：

• 操作系统：macOS Sonoma
• Python版本：Python 3.11
• IDE：PyCharm 2025 专业版
• 包管理器：pip 24.x

这些环境并不会直接导致错误，但结合项目配置可能会触发 ModuleNotFoundError。

---

二、常见错误场景复盘

在 PyCharm 中执行：

pip install websockets

安装日志显示成功，但运行 import websockets 时依然报错。这往往意味着：

1. 包未被安装到当前解释器的环境中。
2. 虽然安装了，但导入路径错了。
3. pip、环境或包版本存在冲突。

---

三、错误原因与解决方案详解

1. 模块未安装或包名错误

很多同学输入命令时拼写错误，例如：

pip install websocket   # ❌ 错误
pip install websockets  # ✅ 正确

解决方法 ：确认 pip list 中存在 websockets 包。

---

2. pip 版本过旧

部分老版本 pip 与新版 PyPI 协议不兼容，可能导致安装成功但不可用。

pip install --upgrade pip

---

3. 网络问题（国内用户常见）

国内环境下可能因为网络原因导致包下载不全。

解决方案：切换国内源（例如清华镜像）：

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

---

4. 环境与解释器不一致

PyCharm中可能启用了多个 Python 解释器。

检查路径：
PyCharm -> Preferences -> Project Interpreter

确认解释器与执行 pip install 的环境一致。

---

5. 忘记 import 或导错包

# 错误示例
import websocket   # ❌

# 正确示例
import websockets  # ✅

---

6. 缺少 __init__.py 文件

如果是自己封装的模块目录，没有 __init__.py 会导致 Python 不能识别为 package。

touch __init__.py

---

7. 包版本不兼容

某些依赖库要求特定版本。例如 FastAPI 需要 websockets ≥ 10.0。

pip install websockets==11.0.3

---

8. 自定义包名冲突

如果你在项目目录中创建了一个叫 websockets.py 的文件，会覆盖掉系统安装的库。

解决方法：避免与第三方库同名。

---

9. PYTHONPATH 未设置

如果安装的路径不在 PYTHONPATH 下，运行时会找不到模块。

export PYTHONPATH=$PYTHONPATH:/usr/local/lib/python3.11/site-packages

---

10. 相对导入错误

# ❌ 错误
from . import websockets

# ✅ 正确
import websockets

---

---

四、解决流程可视化

成功 报错 正确 仍报错 最终解决 执行 pip install websockets import websockets 成功 检查拼写是否正确 检查解释器和环境一致性 升级pip / 切换国内源 / 检查PYTHONPATH

---

五、常见问题对照表

问题现象	可能原因	解决方法
安装成功但仍报错	环境不一致	确认PyCharm解释器
No module named websockets	包名拼写错误	使用 pip install websockets
下载缓慢或失败	网络问题	切换清华源或阿里源
导入时冲突	自定义包名相同	重命名自定义模块
安装后无法调用	pip版本旧	pip install --upgrade pip
项目结构问题	缺少 __init__.py	添加该文件

---

六、总结与扩展思路

通过上面的分析，可以看到 ModuleNotFoundError 不一定真的是"没有安装"，而可能是 路径、解释器、网络、版本冲突 等导致的。

利他提醒 ：如果你在开发中遇到更多 Python、PyCharm、pip 等相关Bug，可以参考 ==> 全栈Bug解决方案专栏 https://blog.csdn.net/lyzybbs/category_12988910.html

这样不仅能解决单个问题，也能提升整体开发排错能力。 🚀

---