Fix pip "error: externally-managed-environment" on Linux

sudo apt install python3-venv        # Debian/Ubuntu/Mint; Arch has venv built in
python3 -m venv ~/.venvs/myproject
source ~/.venvs/myproject/bin/activate
pip install requests

What the error means

Running pip install (or pip3 install, or sudo pip install) outside a virtual environment prints:

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.13/README.venv for more information.

note: If you believe this is a mistake, please contact your Python installation or OS distribution provider. You can override this, at the risk of breaking your Python installation or OS, by passing --break-system-packages.
hint: See PEP 668 for the detailed specification.

This is not a bug. Your distribution's own tools (the package manager helpers, firewall tools, desktop utilities) are written in Python and depend on exact library versions installed by apt or pacman. PEP 668 lets a distribution mark its Python as "externally managed" by placing a file named EXTERNALLY-MANAGED in the standard library directory. When pip sees it, it refuses to install outside a virtual environment, so it cannot overwrite those libraries. The text differs slightly on Arch, which suggests pacman -S python-xyz.

Distributions enforcing this include Debian 12 and newer, Ubuntu 23.04 and newer (so Ubuntu 24.04 and 26.04), Linux Mint 22 and newer, and Arch Linux. Fedora currently does not ship the marker (still true on Fedora 44), so the error does not appear there.

Fix 1: use a virtual environment (projects and scripts)

A venv is a private copy of the Python environment in a directory you own. pip inside it is allowed to do anything, and nothing leaks into the system.

# Debian, Ubuntu, Mint: venv support is a separate package
sudo apt install python3-venv python3-pip
# create and activate
python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
# leave it
deactivate

You do not have to activate the venv to use it. Scripts, cron jobs and systemd services can call its interpreter directly:

/home/you/project/.venv/bin/python /home/you/project/app.py

If the venv command fails with ensurepip is not available, the python3-venv package (or the version-specific one it names, such as python3.13-venv) is missing. Tools such as uv (uv venv, uv pip install) also create standard venvs and work fine with this restriction.

Fix 2: use pipx (command-line applications)

If you want a program you run from the terminal rather than a library you import, pipx gives each one its own hidden venv and puts the command on your PATH:

# Ubuntu/Debian/Mint
sudo apt install pipx
# Arch
sudo pacman -S python-pipx
# Fedora
sudo dnf install pipx

pipx ensurepath          # adds ~/.local/bin to PATH; open a new terminal after
pipx install yt-dlp
pipx upgrade-all

If the command is not found afterwards, ~/.local/bin is not on your PATH yet; see "command not found".

Fix 3: install the distro package

For libraries used by system scripts, or when you just need a common module, the packaged version is the right choice. It gets security updates with the rest of the system.

Search with apt search python3-NAME or pacman -Ss python-NAME. If apt reports nothing, see "Unable to locate package"; not every PyPI project is packaged, and then a venv is the answer.

Fix 4: let a venv see system packages

Some libraries are painful to build from PyPI (GTK bindings, GDAL, large scientific stacks). Install them with apt and create a venv that can import them, while still installing everything else privately:

sudo apt install python3-gi python3-gdal
python3 -m venv --system-site-packages .venv
source .venv/bin/activate
pip install some-extra-package

When --break-system-packages is acceptable

It is reasonable in a single-purpose container image or CI job where nothing else uses that Python and the image is rebuilt from scratch. Even there, python -m venv /opt/venv in the Dockerfile is the cleaner option and costs a few seconds.

How to prevent it

• Create one venv per project and commit a requirements.txt or pyproject.toml, not the venv itself.
• Use pipx for every Python CLI tool you install from PyPI.
• Do not run sudo pip. Anything that needs root should come from the package manager; the package manager comparison shows the commands per distro.
• In shell scripts, call the venv's interpreter by full path rather than relying on activate; the bash scripting guide covers this pattern.

Frequently asked questions