# 错误：外部管理环境

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

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

## 根因

PEP 668：操作系统通过 EXTERNALLY-MANAGED 标记将其 Python 安装标记为外部管理，因此 pip 拒绝安装到系统 site-packages。

## 版本兼容性

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

## 解决方案

1. **** (95% 成功率)
   ```
   Create and use a virtual environment: `python -m venv .venv && source .venv/bin/activate && pip install foo`.
   ```
2. **** (85% 成功率)
   ```
   Install via the OS package manager if available: `sudo apt install python3-foo`, or use `pipx` for CLI apps: `pipx install foo`.
   ```

## 无效尝试

- **** — Overrides the safety guard and can break OS tooling that depends on system packages. (40% 失败率)
- **** — Still blocked by the externally-managed marker and risks system damage. (70% 失败率)