解决 pip3 安装 WebSocket 时报错 “externally-managed-environment”

在使用 pip3 install websocket 时，可能会遇到以下错误提示：

error: externally-managed-environment

× This environment is externally managed
╰─> To install Python packages system-wide, try brew install xyz, where xyz is the package you are trying to install.

该错误的主要原因是 Python 基础环境被标记为“外部管理”，系统默认不允许直接在全局环境中安装或修改 Python 包，以防止影响系统稳定性。文章源自堕落的鱼-https://www.duoluodeyu.com/2819.html

解决方法

实际上，解决方案已经写在了报错信息中，最简单的方式就是 向 pip 传入 --break-system-packages 选项，强制安装：文章源自堕落的鱼-https://www.duoluodeyu.com/2819.html

pip install --break-system-packages websocket

这样就可以绕过系统的限制，成功安装 websocket 库。文章源自堕落的鱼-https://www.duoluodeyu.com/2819.html

错误原因解析

从 Python 3.11 开始，部分操作系统（如 Ubuntu 22.04+ 和 macOS Homebrew）对系统自带的 Python 进行了“外部管理”（Externally Managed）。其目的是防止 pip 在全局环境中安装或升级 Python 包，从而破坏系统组件或软件包依赖关系。文章源自堕落的鱼-https://www.duoluodeyu.com/2819.html

Python 官方的 PEP 668 详细解释了这一变更。如果新安装的软件包（或其依赖项之一）是通过操作系统发行版提供的 Python 组件的更新版本，可能会导致软件不兼容，甚至影响系统稳定性。文章源自堕落的鱼-https://www.duoluodeyu.com/2819.html

其他解决方案

如果不想每次安装都添加 --break-system-packages，可以采用以下方法之一：文章源自堕落的鱼-https://www.duoluodeyu.com/2819.html

1. 在 pip.conf 中永久添加该选项

编辑或创建 pip.conf 文件：文章源自堕落的鱼-https://www.duoluodeyu.com/2819.html

mkdir -p ~/.config/pip
echo '[global]' >> ~/.config/pip/pip.conf
echo 'break-system-packages = true' >> ~/.config/pip/pip.conf

这样以后使用 pip install 就不会再出现这个错误提示。文章源自堕落的鱼-https://www.duoluodeyu.com/2819.html

2. 使用 --user 安装（推荐）

如果只是想在当前用户环境下安装软件包，而不是全局安装，可以使用 --user 选项：文章源自堕落的鱼-https://www.duoluodeyu.com/2819.html

pip install --user websocket

这样，软件包会被安装到 ~/.local/lib/pythonX.X/site-packages/ 目录，不会影响系统 Python 环境。文章源自堕落的鱼-https://www.duoluodeyu.com/2819.html

3. 使用虚拟环境（强烈推荐）

Python 官方推荐使用虚拟环境来管理依赖，以避免污染全局环境。

创建并激活虚拟环境：

python3 -m venv myenv
source myenv/bin/activate  # Windows 用户使用 myenv\Scripts\activate
pip install websocket

使用完毕后，可通过 deactivate 退出虚拟环境。

总结

• 临时解决方案：添加 --break-system-packages 强制安装。
• 长期方案：修改 pip.conf，或使用 --user 进行安装。
• 最佳实践：使用虚拟环境管理 Python 依赖。

如果你频繁遇到类似问题，建议尽可能采用 虚拟环境，以避免影响系统的 Python 组件。