pip “error: externally-managed-environment”: why it happens and the right fix
Your operating system’s Python belongs to the operating system. Since PEP 668, distributions mark it as “externally managed” so that pip can’t overwrite packages the system itself depends on. Nothing is broken; pip is asking you to install somewhere else.
What the error looks like
$ pip install requests
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.You’ll see it on Ubuntu 23.04 and later (including 24.04 LTS), Debian 12, recent Fedora and Arch, Raspberry Pi OS Bookworm, and Python installed by Homebrew on macOS. The trigger is a small file named EXTERNALLY-MANAGED next to the standard library, for example /usr/lib/python3.12/EXTERNALLY-MANAGED.
Why it exists
Tools like the package manager, the firewall front-end or the desktop itself are written in Python and rely on exact versions of libraries in the system Python. A sudo pip install that upgraded one of those libraries could quietly break the OS, and apt would have no idea. PEP 668 lets the distribution say “this Python is mine”, and pip now refuses rather than guess.
Fix 1: a virtual environment (for projects)
sudo apt install python3-venv # Debian/Ubuntu only, once
python3 -m venv .venv
source .venv/bin/activate # prompt now starts with (.venv)
pip install -r requirements.txt
python app.pyEverything goes into the .venv folder, owned by you, no sudo. Delete the folder to start over. Add .venv/ to .gitignore. In a systemd service or cron job, skip activation and call the venv’s interpreter directly: /srv/app/.venv/bin/python app.py.
Fix 2: pipx (for command-line tools)
sudo apt install pipx # or: brew install pipx
pipx ensurepath # adds ~/.local/bin to PATH; open a new shell
pipx install yt-dlppipx gives each tool its own hidden virtual environment and puts just the command on your PATH, so tools never fight over versions. pipx upgrade-all keeps them current.
Fix 3: the distribution’s package
For libraries the system scripts need anyway, sudo apt install python3-requests (or dnf install python3-requests, pacman -S python-requests) installs a tested version that the package manager tracks. It may be older than PyPI’s.
Which one should I use?
| You want to… | Use |
|---|---|
| Work on a project or run a script with dependencies | A virtual environment (venv, or uv venv / Poetry) |
Install a command such as black, ansible, yt-dlp | pipx install (or uv tool install) |
| Satisfy a system script or another apt package | apt install python3-xyz |
| Throwaway container or CI image that only runs your app | A venv is still cleanest; --break-system-packages is tolerable here |
About --break-system-packages
pip install --break-system-packages requests, or setting PIP_BREAK_SYSTEM_PACKAGES=1, switches the check off. The name is honest: on a real machine it can break system tools, and the next OS upgrade may undo or clash with what you installed. pip install --user is blocked too, because packages in ~/.local still shadow the system’s. Deleting the EXTERNALLY-MANAGED file works until the next Python update puts it back; don’t.
In Docker
Official python:3.x images don’t have the marker, so pip install just works. Images based on ubuntu:24.04 or debian:12 do. Either switch the base image or create a venv in the Dockerfile and put it first on PATH:
RUN python3 -m venv /opt/venv
ENV PATH="/opt/venv/bin:$PATH"
RUN pip install -r requirements.txtInstalled the package but Python still can’t find it? The interpreter running your code isn’t the one pip installed into: see ModuleNotFoundError: No module named. Comparing two pip freeze outputs in the text diff tool shows exactly what differs between environments.
Activating the venv on Windows blocked? See running scripts is disabled on this system. Venv created but the wrong Python still runs? See venv not activating / which python.
Related
metadata-generation-failed · Failed building wheel · pip: Could not find a version
Questions
What does error: externally-managed-environment mean?
Your Linux distribution or Homebrew has marked its Python as managed by the system package manager (PEP 668), so pip refuses to install into it. Install into a virtual environment or use pipx instead.
How do I pip install on Ubuntu 24.04?
Create a virtual environment with python3 -m venv .venv, activate it with source .venv/bin/activate, and run pip install inside it. Use pipx for command-line tools, or apt install python3-name for system-wide libraries.
Is --break-system-packages safe?
Only on a disposable machine or container. On a normal system it can overwrite libraries that OS tools depend on and break them, which is exactly what the error is protecting you from.
Why does pip install --user also fail?
Packages in your user site folder are loaded ahead of the system's, so they can break system scripts just the same. The PEP 668 check blocks --user installs too.
Published · updated .