On Ubuntu 23.04+, Debian 12 and other modern distributions, pip install something fails with error: externally-managed-environment. This is deliberate (PEP 668): the system Python belongs to the OS package manager, and pip installs could break system tools. The fix is to install packages somewhere else.
Before you start
- SSH access; root is only needed for apt installs.
- Decide what you are installing: libraries for an app, or a command-line tool.
Option 1: a virtual environment (for apps)
The standard approach for any Python project:
apt install python3-venvpython3 -m venv /srv/myapp/venv/srv/myapp/venv/bin/pip install -r requirements.txtActivate it in an interactive shell with source /srv/myapp/venv/bin/activate; afterwards pip and python point to the venv. In systemd units and cron jobs, call the venv's binaries directly (/srv/myapp/venv/bin/python, /srv/myapp/venv/bin/gunicorn) instead of activating.
Option 2: pipx (for command-line tools)
For tools like certbot plugins, yt-dlp, ansible or httpie, pipx creates an isolated environment per tool and puts the command on your PATH:
apt install pipx && pipx ensurepathpipx install httpieUpgrade later with pipx upgrade-all.
Option 3: the distribution package
Many libraries are packaged as python3-*:
apt install python3-requests python3-yamlThey are maintained with OS updates but may be older versions. Good for system scripts; for apps, prefer a venv.
What about --break-system-packages?
pip accepts --break-system-packages to override the protection. As the name warns, it can overwrite packages that apt manages and break OS tools such as apt itself or cloud-init. Avoid it on servers. A pip install --user also triggers the error now, for the same reason.
Docker images
Inside a container that runs only your app, the official python:3.x images are not "externally managed" and pip works normally. On Debian/Ubuntu-based images with the system Python, use a venv in the Dockerfile.
Check that it works
/srv/myapp/venv/bin/python -c "import requests; print(requests.__version__)"Troubleshooting
- The virtual environment was not created successfully because ensurepip is not available: install
python3-venv(orpython3.12-venvfor a specific version). - Command installed by pipx not found: run
pipx ensurepathand open a new shell, or add~/.local/binto PATH. - Building wheels fails: install build dependencies, e.g.
apt install build-essential python3-devplus library headers likelibpq-dev.
pip error FAQ
Why did this start suddenly?
Newer distro releases ship an EXTERNALLY-MANAGED marker file with their Python, which recent pip versions respect.
Does each app need its own venv?
Yes, that keeps dependency versions separate and upgrades safe.
How does cPanel handle this?
Setup Python App creates a virtual environment for each app automatically.