# 错误：externally-managed-environment（环境由外部管理）
此环境由外部管理，无法直接安装系统级 Python 包。

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

## 根因

PEP 668：Debian/Ubuntu（及 Fedora）在系统 Python 中放置 `EXTERNALLY-MANAGED` 标记文件，使 pip 拒绝安装到系统环境，防止破坏操作系统管理的包。

## 版本兼容性

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

## 解决方案

1. **** (95% 成功率)
   ```
   Create and use a virtual environment (the intended workflow):

python3 -m venv .venv
source .venv/bin/activate
pip install <pkg>
   ```
2. **** (85% 成功率)
   ```
   Install via the OS package manager when a distro package exists:

sudo apt install python3-requests

For user-level installs without venv, use pipx for applications or `pip install --user` after creating a venv.
   ```

## 无效尝试

- **** — It works but writes into the OS-managed site-packages; a later apt upgrade can overwrite or break the package, and vice versa. Frequently corrupts the system Python. (65% 失败率)
- **** — Removing the marker bypasses the guard but does not solve the underlying problem; the next apt upgrade reinstalls the marker and can clobber your packages. (60% 失败率)