# 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-externally-managed-environment-pep668`
- **Domain:** python
- **Category:** install_error
- **Verification:** ai_generated
- **Fix Rate:** 80%

## Root Cause

PEP 668 marks the system Python as externally managed via an EXTERNALLY-MANAGED marker file. Debian/Ubuntu and Homebrew ship this to prevent pip from breaking the OS package manager.

## Version Compatibility

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

## Workarounds

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

## Dead Ends

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