# 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/externally-managed-environment-full-message`
- **Domain:** pip
- **Category:** config_error
- **Error Code:** `error`
- **Verification:** ai_generated
- **Fix Rate:** 95%

## Root Cause

The Python environment is marked as externally managed (e.g., on Debian/Ubuntu systems with PEP 668 support), preventing pip from installing packages system-wide to avoid conflicts with the system package manager.

## Version Compatibility

| Version | Status | Introduced | Deprecated |
|---------|--------|------------|------------|
| pip 23.0 | active | — | — |
| pip 23.1 | active | — | — |
| pip 23.2 | active | — | — |
| pip 24.0 | active | — | — |

## Workarounds

1. **Create and use a virtual environment: 'python3 -m venv /path/to/venv' then 'source /path/to/venv/bin/activate' and install packages inside it.** (95% success)
   ```
   Create and use a virtual environment: 'python3 -m venv /path/to/venv' then 'source /path/to/venv/bin/activate' and install packages inside it.
   ```
2. **Use pipx for installing CLI applications: 'pipx install <package>'.** (90% success)
   ```
   Use pipx for installing CLI applications: 'pipx install <package>'.
   ```

## Dead Ends

- **** — This can break the system Python installation and cause conflicts with apt-managed packages, leading to system instability. (50% fail)
- **** — This removes the protection entirely and may cause the same issues as --break-system-packages; also, updates to the python3 package may restore the file. (60% fail)