Fixing “externally-managed-environment” When Using pip

error: externally-managed-environment means the Python you are running belongs to the operating system or a package manager, and pip has been told not to install into it. The message is long and looks alarming; the situation is simple. Install into a virtual environment instead, or use the tool built for installing command-line applications, and the error never appears. The override flag exists and is almost never the right answer.

Why the error exists#

On Debian, Ubuntu, Fedora and macOS with Homebrew, Python is part of the system. Tools the OS itself relies on are written in it. For years, sudo pip install into that Python was how people upgraded a library and quietly broke apt, or the desktop, or the package manager that would have fixed it. A Python standard, PEP 668, lets distributions mark their interpreter as externally managed, and pip honours the mark. Ubuntu 23.04 and later, Debian 12 and later, recent Fedora and current Homebrew all do.

The error is not a bug in pip or a broken installation. It is a fence around the system’s Python.

Fix 1: a virtual environment#

For any project, this is the answer:

python3 -m venv .venv
source .venv/bin/activate
pip install requests          # goes into .venv, no error

On some Debian and Ubuntu systems the venv module is packaged separately:

sudo apt install python3-venv

Inside the environment, pip and python refer to the project’s own copies, packages are isolated per project, and the system Python is untouched. Deactivate with deactivate. If you use uv, uv venv followed by uv pip install is the same idea, faster.

Fix 2: pipx for tools#

For a program you run from the command line — a formatter, a linter, a utility — a virtual environment per project is the wrong shape; you want it available everywhere. pipx installs each tool into its own hidden environment and puts the command on your PATH:

sudo apt install pipx          # or: brew install pipx
pipx ensurepath                # then open a new terminal
pipx install ruff
pipx install httpie
ruff --version

Tools stay isolated from each other and from the system. pipx upgrade-all updates them. uv offers the same with uv tool install.

Fix 3: the system package manager#

If a library genuinely needs to be available to system Python — for a system service, or a script the OS runs — install the distribution’s package of it:

apt search python3-requests
sudo apt install python3-requests

The versions are older than PyPI’s, and that is the point: they are tested with the rest of the system. For development work this is rarely what you want; use a virtual environment.

The override#

pip install --break-system-packages requests

The flag’s name is the documentation. It does exactly what the fence was built to prevent. The narrow cases where it is acceptable: a throwaway container image that exists only to run one script, or a machine you are about to reinstall. On a system you keep, it is the road back to the problems PEP 668 fixed.

Setting it permanently in pip’s configuration — you will find this advice online — is the same decision made once and forgotten, which is worse.

Docker#

The official python images are not externally managed; pip installs normally. The error appears in images based on ubuntu or debian that install Python with apt. Either use the official Python image, or create a virtual environment in the Dockerfile:

FROM ubuntu:24.04
RUN apt-get update && apt-get install -y python3 python3-venv && rm -rf /var/lib/apt/lists/*
RUN python3 -m venv /opt/venv
ENV PATH="/opt/venv/bin:$PATH"
COPY requirements.txt .
RUN pip install -r requirements.txt

Putting the environment’s bin first on the PATH means every later pip and python in the image uses it without activation.

Jupyter, PyTorch and data tools#

The error turns up constantly in data-science setups because tutorials say pip install torch with no environment. The answer is the same: create a virtual environment, install the tools into it, and register it as a Jupyter kernel if you use notebooks:

python3 -m venv ~/ml-env
source ~/ml-env/bin/activate
pip install torch jupyter ipykernel
python -m ipykernel install --user --name ml-env

Conda users do not see this error at all, because conda manages its own Python.

Where to go next#

• Python virtual environments — the fix, in depth.
• uv vs pip — the tool that manages environments for you.
• Python not working on a Mac — the Homebrew side of this.