Ubuntu/Debian pip install 报 error: externally-managed-environment（PEP 668）

你会遇到什么

新装的 Ubuntu（或 WSL）上 pip install 任何包都直接报 error: externally-managed-environment，连 pip install numpy 都装不了。你以为是 Python 3.14 太新、或 pip 坏了，甚至想降级 Python——其实都不是：这是发行版的默认安全策略，pip 只是按规矩拒绝往系统环境里装。

本文路径：快速修复（30 秒一段命令）→ 一步步排查（可跳读）→ 原理与变体（症状/原因/证据）。赶时间直接跳到「快速修复」。

为什么会这样

Ubuntu 23.04 起默认开启 PEP 668：系统 Python 被标记为 "externally managed"，pip 拒绝直接向系统环境安装第三方包，防止第三方包覆盖 apt 管理的系统包、把系统 Python 搞坏。

• 报错与 Python 版本无关，任何包、任何时候都触发，这是设计行为。
• 正确解法不是绕过检查，而是改用虚拟环境：venv 是独立环境，pip 随便装，与系统互不污染。

实测环境：WSL Ubuntu，Python 3.14.4 / pip 25.1.1，2026-08-29。

PEP 668 是「环境所有权」声明：系统 Python 的 site-packages 由 apt/发行版包管理器持有，pip 直接写入会与 apt 的包记录脱节（apt 不知道 pip 装了什么、升级时可能覆盖，pip 也不知道 apt 动过什么）。发行版用一个标记文件（EXTERNALLY-MANAGED）声明所有权，pip 检测到就拒绝。

确定性推论：报 externally-managed-environment 与包名/版本无关，是目标环境的问题；解法是换环境而不是绕过（--break-system-packages 是「我知道会弄脏系统」的显式声明，只适合容器/一次性环境）；venv 之所以永远不报，是因为它自带独立 site-packages 且不声明 externally-managed；

判断路径固定：先 python3 -m venv .venv 建独立环境再 pip，而不是跟系统 Python 搏斗。

一步步来

1. 建虚拟环境 — 必做

python3 -m venv .venv

报 ensurepip is unavailable 就先装：sudo apt install python3-venv（精简镜像常见）。

2. 激活 — 必做

source .venv/bin/activate

激活后提示符前出现 (.venv)，此时 pip 已指向虚拟环境（实测：venv 内 pip install six 直接成功）。

3. 正常安装 — 必做

pip install -r requirements.txt

以后进项目先 source .venv/bin/activate 即可，不再遇到 PEP 668。

4. 命令行工具用 pipx（可选） — 进阶

系统级命令行应用优先 pipx install <应用>——pipx 自动为每个应用建独立虚拟环境，不碰系统 Python，也不报 PEP 668。

单次救急可用 pip install <包> --break-system-packages，但会跳过保护、可能覆盖系统包，不推荐长期用。

怎么确认修好了

source .venv/bin/activate && pip install six && python -c "import six; print(six.__version__)"

不再报 externally-managed-environment、能正常 import 即成功（实测：venv 内安装成功；dry-run --break-system-packages 路径也验证过会输出 Would install six-1.17.0）。

其它环境的表现

症状

在 Ubuntu/Debian（含 WSL 新装的 Ubuntu 26.04）上直接 pip install <包> 立即报错：

error: externally-managed-environment
× This environment is externally managed
╰─> To install Python packages system-wide, try apt install ...

特征：装任何包都失败，与项目依赖无关（连 pip install numpy 都装不了）；容易误判成 Python 3.14 的版本问题，甚至想降级 Python。

原因

Ubuntu 26.04 等 Debian 系系统默认开启 PEP 668：系统 Python 被标记为 "externally managed"，pip 拒绝直接向系统环境安装第三方包，防止第三方包覆盖 apt 管理的系统包、搞坏系统 Python。这不是 Python 3.14 的 bug，而是发行版默认策略（自 Ubuntu 23.04 起默认开启）。

解法

1. 长期正确姿势（推荐）：建虚拟环境，之后正常 pip install 不再报错：

   python3 -m venv .venv
   source .venv/bin/activate
   pip install -r requirements.txt

提示：若报缺 ensurepip，先 sudo apt install python3-venv（精简镜像常见）。

1. 临时绕过（单次救急）：pip install <包> --break-system-packages —— 跳过 PEP 668 检查；代价是可能覆盖系统包、与 apt 冲突，不推荐长期使用。
2. 系统级/命令行工具：优先 apt install python3-<包名>；命令行应用用 pipx install <应用>（pipx 自动管理独立虚拟环境）。