问题是什么？

在 Debian、Ubuntu、Fedora 等最新的Linux发行版，以及Docker容器软件提供的终端（例如 code-server）中尝试使用 pip install 安装 Python 包 时，通常会收到一个错误提示：error: externally-managed-environment。

❯ sudo python -m pip install --user pygame
error: externally-managed-environment
 
× This environment is externally managed
╰─> To install Python packages system-wide, try apt install
    python3-xyz, where xyz is the package you are trying to
    install.
    
    If you wish to install a non-Debian-packaged Python package,
    create a virtual environment using python3 -m venv path/to/venv.
    Then use path/to/venv/bin/python and path/to/venv/bin/pip. Make
    sure you have python3-full installed.
    
    For more information visit http://rptl.io/venv
 
note: If you believe this is a mistake, please contact your Python installation or OS distribution provider. You can override this, at the risk of breaking your Python installation or OS, by passing --break-system-packages.
hint: See PEP 668 for the detailed specification.

为什么会这样呢？

出现 externally-managed-environment 错误说明当前 Python 环境是由系统包管理器（如 apt、dnf、pacman）管理的。系统禁止直接用 pip 安装 Python 包，以防止用户操作破坏系统依赖的完整性（例如与 apt 安装的 Python 包冲突）。

如何解决？

📦 使用系统包管理器安装

使用系统自带的包管理器无疑是最便捷&简单的方法，假如你想安装 requests 包，下列命令列出了常用系统的安装命令.

# Debian/Ubuntu
sudo apt install python3-requests

# CentOS/RHEL 8+/Fedora
sudo dnf install python3-requests
 
# Arch/Manjaro
sudo pacman -S python-requests 

# openSUSE
sudo zypper install python3-requests 

# Apline Linux
sudo apk add py3-requests 

🧐 包名命名规则

• 大多数发行版使用 python3- 作为前缀
• Arch/Manjaro 使用 python- 作为前缀
• Alpine 使用 py3- 作为前缀

🐍 创建并使用虚拟环境（推荐）

使用虚拟环境安装和管理 Python 包是最常见的方法，简单而有效。创建并激活虚拟环境后，pip install 将畅通无阻！

创建并虚拟环境的命令如下：

# 创建名叫 myenv 的虚拟环境
python3 -m venv myenv

# 激活此虚拟环境
source myenv/bin/activate

# 使用 pip 安装 Python 包（需要将 [package] 替换为实际包名，例如 requests）
pip install [package]

🚀 使用 pipx 管理（适用于独立应用）

对于需要直接运行的应用（例如 nb-cli），推荐使用 pipx 安装。pipx 会为每一个安装的应用创建虚拟环境并添加至 PATH，确保你可以直接运行而不会出现依赖问题。

一般情况下，安装 Python 环境不会顺带安装 pipx，你需要手动安装才能使用：

# Debian/Ubuntu
sudo apt install python3-pipx

# 配置 pipx 环境变量
pipx ensurepath

安装完成并配置环境变量后，便可以通过

# 将 [package] 替换为实际包名
pipx install [package]

来安装你需要安装的包/Python 应用。

🤪 无视风险，继续安装

如果你是 紧急需求/作死 或其他原因，可以尝试该方法，无视 pip 的警告，强制将 Python 包安装至系统环境。仅需在正常 pip install 命令后添加 --break-system-packages，即可无视风险强制安装。

# 将 [package] 替换为实际包名
pip install [package] --break-system-packages

📚 总结

本文提供了 4种 方法解决安装 Python 包时产生的 externally-managed-environment 错误。希望这篇指南帮助你成功安装 Python 包！ 如果还有其他 Linux/Python 问题，欢迎在评论区留言讨论！觉得有用的话，不妨分享给遇到相同问题的朋友吧～