pip "error: externally-managed-environment": install Python packages the right way

1. The package from apt

Many popular libraries are packaged by the distribution as python3-<name>:

apt search python3-requests
sudo apt install python3-requests python3-yaml

They are tested with the system’s Python and updated with apt upgrade. The catch: you get the version the distribution chose, which can be older than the newest one on PyPI. Fine for system scripts; for a real project, use a virtual environment.

2. A virtual environment (for projects)

A virtual environment is a folder with its own Python and its own packages. pip may install anything there, and nothing outside it is affected:

sudo apt install python3-venv           # once (python3-full also brings it)
python3 -m venv .venv                   # create it in your project folder
source .venv/bin/activate               # use it in this shell
pip install requests                    # works — installs into .venv

While it’s active, python and pip are the ones in .venv. deactivate leaves it. In scripts, cron jobs and systemd services you don’t need activate — call the environment’s Python directly:

/opt/myapp/.venv/bin/python /opt/myapp/main.py

Keep the list of packages in requirements.txt (pip freeze > requirements.txt) and put .venv/ in .gitignore: the folder is easy to recreate, and it doesn’t work if you copy it to another path.

3. pipx (for command-line tools)

For tools you run as commands, a project folder is overkill. pipx creates one hidden virtual environment per tool and puts the command on your PATH:

sudo apt install pipx
pipx ensurepath          # adds ~/.local/bin to PATH (open a new shell after it)
pipx install httpie
http --version

pipx upgrade-all updates every tool, pipx uninstall httpie removes one cleanly.

4. –break-system-packages: when it’s acceptable

The flag does exactly what it says: it lets pip write into the system’s Python anyway. On a server or your workstation, don’t — the day pip upgrades a package that apt or cloud-init depends on, those tools start failing in confusing ways, often at the next OS upgrade.

pip install --user doesn’t avoid the problem either: it’s blocked too, because packages in ~/.local still override the system’s ones for your user.

The one place it’s reasonable is a container that exists only to run your app, built from a Debian or Ubuntu image with the system’s Python:

FROM debian:12-slim
RUN apt-get update && apt-get install -y --no-install-recommends python3 python3-pip \
 && rm -rf /var/lib/apt/lists/*
COPY requirements.txt .
RUN pip install --break-system-packages --no-cache-dir -r requirements.txt

Even there, a virtual environment in the image is cleaner. Or simply start from the official python image — its Python isn’t the distribution’s, so pip works there without any flag.