# 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.

- **ID:** `python/pip-error-externally-managed-environment`
- **Domain:** python
- **Category:** install_error
- **Verification:** ai_generated
- **Fix Rate:** 80%

## Root Cause

PEP 668: Debian/Ubuntu (and Fedora) mark the system Python with an `EXTERNALLY-MANAGED` marker file so pip refuses to install into it, preventing breakage of OS-managed packages.

## Version Compatibility

| Version | Status | Introduced | Deprecated |
|---------|--------|------------|------------|
| 3.11 | active | — | — |
| 3.12 | active | — | — |
| 3.13 | active | — | — |

## Workarounds

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

python3 -m venv .venv
source .venv/bin/activate
pip install <pkg>
   ```
2. **** (85% success)
   ```
   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.
   ```

## Dead Ends

- **** — 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% fail)
- **** — 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% fail)