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

## Root Cause

PEP 668: the OS marks its Python installation as externally managed (via EXTERNALLY-MANAGED marker), so pip refuses to install into system site-packages.

## Version Compatibility

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

## Workarounds

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

## Dead Ends

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