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

If you wish to install a non-Debian-packaged Python package,
create a virtual environment using python3 -m venv path/to/venv.
Then use path/to/venv/bin/python and path/to/venv/bin/pip. Make sure you have python3-full installed.

If you wish to install a non-Debian packaged Python application,
it may be easiest to use pipx install xyz, which will manage a
virtual environment for you. Make sure you have pipx installed.

See /usr/share/doc/python3.11/README.venv for more information.

- **ID:** `pip/pep-668-externally-managed-environment`
- **Domain:** pip
- **Category:** install_error
- **Error Code:** `error`
- **Verification:** ai_generated
- **Fix Rate:** 92%

## Root Cause

Debian/Ubuntu systems mark the system Python installation as externally managed (via PEP 668) to prevent pip from overwriting packages managed by the system package manager, but users attempt to install packages globally with pip outside a virtual environment.

## Version Compatibility

| Version | Status | Introduced | Deprecated |
|---------|--------|------------|------------|
| pip 23.0+ | active | — | — |
| Debian 12 | active | — | — |
| Ubuntu 23.04+ | active | — | — |
| Python 3.11 | active | — | — |

## Workarounds

1. **Create and use a virtual environment: python3 -m venv myenv && source myenv/bin/activate && pip install <package>** (95% success)
   ```
   Create and use a virtual environment: python3 -m venv myenv && source myenv/bin/activate && pip install <package>
   ```
2. **Use pipx for installing CLI applications: pipx install <package>** (90% success)
   ```
   Use pipx for installing CLI applications: pipx install <package>
   ```
3. **Install the package via apt if available: apt install python3-<package>** (85% success)
   ```
   Install the package via apt if available: apt install python3-<package>
   ```

## Dead Ends

- **Running pip with --break-system-packages flag** — This flag bypasses the protection but may break system tools that depend on specific package versions, leading to system instability or broken apt packages. (30% fail)
- **Removing the EXTERNALLY-MANAGED file from /usr/lib/python3.x/** — Deleting the marker file permanently disables the protection, but future system updates may restore it, and it violates the distribution's design intent. (40% fail)
- **Installing packages with sudo pip install** — Running pip as root in a system environment can corrupt system Python packages, cause permission conflicts, and is strongly discouraged by Python packaging guidelines. (60% fail)