# 错误：外部管理环境

× 此环境由外部管理
╰─> 要系统级安装 Python 包，请尝试 apt install python3-xyz，其中 xyz 是你要安装的包

- **ID:** `python/pip-externally-managed-environment-pep668`
- **领域:** python
- **类别:** install_error
- **验证级别:** ai_generated
- **修复率:** 80%

## 根因

PEP 668 通过 EXTERNALLY-MANAGED 标记文件将系统 Python 标记为外部管理。Debian/Ubuntu 和 Homebrew 附带此文件，以防止 pip 破坏操作系统包管理器。

## 版本兼容性

| 版本 | 状态 | 引入 | 弃用 |
|------|------|------|------|
| 3.10 | active | — | — |
| 3.11 | active | — | — |
| 3.12 | active | — | — |

## 解决方案

1. **** (98% 成功率)
   ```
   python3 -m venv .venv && source .venv/bin/activate && pip install package
   ```
2. **** (95% 成功率)
   ```
   pipx install some-cli-tool
   ```
3. **** (90% 成功率)
   ```
   pip install --break-system-packages package
   ```

## 无效尝试

- **** — Running as root does not bypass the marker; pip still refuses. (95% 失败率)
- **** — Works but breaks the OS package manager's invariants and is reverted on the next apt upgrade. (40% 失败率)