Troubleshooting

error: externally-managed-environment: why pip refuses and how to fix it

Fix pip error: externally-managed-environment on Debian, Ubuntu and macOS: use a venv, pipx or apt, and why --break-system-packages is a last resort.

Published ~8 min read
On this page

Short answer: error: externally-managed-environment means your operating system owns this Python and has told pip, through a file named EXTERNALLY-MANAGED (PEP 668), not to install into it. Do not force it: create a virtual environment and install there, use pipx for command-line tools, or install the distribution's python3-<name> package.

the fix for most cases · Debian · Ubuntu
sudo apt install python3-venv      # Debian and Ubuntu only, once
python3 -m venv .venv              # a private Python for this project
. .venv/bin/activate               # pip and python now point into .venv
pip install requests               # works: nothing is written to the system

The rest of this page explains where the error comes from, which systems have it, how to check a machine in one line, and which fix fits which case. Installing pip itself is covered in how to install pip, and a missing pip command in pip: command not found.

What the error means

PEP 668 (status Final) gives a distribution a way to say "this Python belongs to my package manager". It drops a small file called EXTERNALLY-MANAGED into the interpreter's standard library directory. pip reads it since version 23.0 (January 2023), and pip 23.0.1 added the --break-system-packages override, per pip's changelog. When the file is there and you are not inside a virtual environment, pip refuses. This is the full message from one of our Debian 12 servers (Python 3.11.2, pip 23.0.1), run in a scratch folder with the package index switched off:

output · Debian 12
$ python3 -m pip install --no-index requests; echo "exit=$?"
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.11/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.
exit=1

Four details explain most of the confusion around it:

  • Nothing was changed. In pip's source the marker check runs right after option checks in pip install, before it resolves or downloads anything, and pip uninstall runs the same check. Exit status 1, no files touched.
  • The middle block is the distribution's text. pip prints the Error key of the marker file, so Ubuntu, Alpine and Homebrew show different advice under the same first line. PEP 668 also allows translated keys such as Error-de_DE, picked by your locale.
  • A venv switches it off. pip skips the check when sys.prefix differs from sys.base_prefix, which is how the Python docs define "running in a virtual environment".
  • It is not a pip bug and not a permission problem. sudo does not get past it, and neither does --user (see below).

Which systems mark their Python as externally managed

SystemMarked?Marker fileSource
Debian 12 bookwormYes, since python3.11 3.11.2-3 (Feb 2023)/usr/lib/python3.11/EXTERNALLY-MANAGEDDebian 12 release notes, package changelog
Debian 13 trixieYes/usr/lib/python3.13/EXTERNALLY-MANAGEDpackages.debian.org file list
Ubuntu 23.04Yes/usr/lib/python3.11/EXTERNALLY-MANAGEDLaunchpad changelog of python3.11
Ubuntu 24.04 and laterYes/usr/lib/python3.12/EXTERNALLY-MANAGED (python3.14 on 26.04)packages.ubuntu.com file lists
Ubuntu 22.04Nonone in libpython3.10-stdlibpackages.ubuntu.com file list
Alpine 3.19 and laterYesin the stdlib directoryAlpine 3.19.0 release notes
Homebrew Python (macOS)Yesin the stdlib directoryHomebrew documentation
Official python Docker imagesNoPython is built from source into /usr/localdocker-library/python Dockerfiles

On Debian the file belongs to libpython3.11-stdlib, so an update of that package puts it back if you delete it. Python compiled from upstream sources is not marked: PEP 668 leaves the decision to whoever distributes the interpreter.

Check whether your Python is marked

pip looks for the file in the stdlib path that sysconfig reports, so ask Python itself instead of guessing the version number. Real output from the same Debian 12 server:

output · Debian 12
$ python3 -c "import sysconfig; print(sysconfig.get_path('stdlib'))"
/usr/lib/python3.11
$ python3 -c 'import os, sysconfig; p = os.path.join(sysconfig.get_path("stdlib"), "EXTERNALLY-MANAGED"); print(p, os.path.isfile(p))'
/usr/lib/python3.11/EXTERNALLY-MANAGED True
$ dpkg -S /usr/lib/python3.11/EXTERNALLY-MANAGED
libpython3.11-stdlib:amd64: /usr/lib/python3.11/EXTERNALLY-MANAGED
$ python3 -c "import sys; print(sys.prefix != sys.base_prefix)"
False

True on the second line means pip will refuse outside a venv. The last line prints True only inside a virtual environment, where the marker is ignored. Run the same lines with the exact interpreter your script uses (for example /usr/local/bin/python3 or a Homebrew path): a machine can have a marked and an unmarked Python side by side.

Fixes, from best to last resort

You want toUseCommand
install libraries for your own codea virtual environmentpython3 -m venv .venv
run a command-line tool from PyPIpipxpipx install NAME
give a system script a common librarythe distribution packagesudo apt install python3-NAME
reuse apt packages plus a few from PyPIa venv with system packagespython3 -m venv --system-site-packages .venv
override the guard in a throwaway containerthe override flagpip install --break-system-packages NAME

1. A virtual environment

This is what the error message and Debian's README.venv recommend. On Debian and Ubuntu the venv module needs the python3-venv package (it depends on python3.11-venv on Debian 12). Without it, our server prints this and leaves a half-built folder behind:

output · Debian 12, python3-venv not installed
$ python3 -m venv .venv
The virtual environment was not created successfully because ensurepip is not
available.  On Debian/Ubuntu systems, you need to install the python3-venv
package using the following command.

    apt install python3.11-venv

You may need to use sudo with that command.  After installing the python3-venv
package, recreate your virtual environment.

Install python3-venv, delete the broken .venv, and create it again. If apt cannot find the package, the package index is missing or stale; see Unable to locate package. Activation is optional: .venv/bin/python and .venv/bin/pip work from any shell, which is what cron jobs and services should call.

2. pipx for command-line apps

For tools you run rather than import (linters, CLIs, small servers), pipx creates one venv per application and links its commands into ~/.local/bin. pipx's own install guide gives this for Ubuntu 23.04 and newer, and Debian 12's archive has pipx 1.1.0:

Debian · Ubuntu
sudo apt install pipx
pipx ensurepath        # adds ~/.local/bin to PATH; open a new shell afterwards
pipx install NAME

On macOS, Homebrew's documentation recommends brew install pipx for the same job.

3. The distribution's package

Many popular libraries are packaged as python3-<name>: Debian 12 has python3-requests 2.28.1 installed on our server, for instance. apt keeps these consistent with the system tools that use them and patches them with security updates. They are older than PyPI. If you need both, a venv created with --system-site-packages sees the apt modules and lets pip add the rest. This ran on our server without pip refusing (no package was installed, requests was already there from apt):

output · Debian 12, venv with system site-packages
$ python3 -m venv --without-pip --system-site-packages demo
$ . demo/bin/activate
$ python -c "import sys; print(sys.prefix != sys.base_prefix)"
True
$ python -m pip install --no-index requests
Requirement already satisfied: requests in /usr/lib/python3/dist-packages (2.28.1)

Why pip install --user does not help

PEP 668 names both cases on purpose: the conflict exists for sudo pip install and for pip install --user, because modules in ~/.local are seen by every Python program you run as that user, the distribution's own tools included. On our server python3 -m pip install --no-index --user requests stops with the same error: externally-managed-environment and exit status 1. Debian's README.venv shows the replacement: instead of pip install --user foo, create ~/.venvs/foo and run ~/.venvs/foo/bin/python -m pip install foo.

Last resort: --break-system-packages

The override exists in three forms, all documented in Debian's README.venv:

override (read the warning first)
pip install --break-system-packages NAME      # one command
PIP_BREAK_SYSTEM_PACKAGES=1 pip install NAME  # one shell or Dockerfile ENV

# ~/.config/pip/pip.conf (you) or /etc/pip.conf (everyone)
[global]
break-system-packages = true

One more loophole to know about: pip 23.0.1 skips the check when you pass --target, --prefix or --root, because it cannot locate a marker for those paths. pip install --target ./vendor NAME into a project folder is harmless; sudo pip install --prefix /usr is the override by another name.

Inside Docker images

The official python:3.x images build CPython from source into /usr/local, and their Dockerfiles contain no EXTERNALLY-MANAGED file, so pip install works there without a venv. The non-slim tags start from buildpack-deps, which pulls in Debian's own /usr/bin/python3 (marked, without pip) as a dependency of mercurial, and the Dockerfile puts /usr/local/bin first on PATH ("ensure local python is preferred over distribution python"). Call python3 and pip by name, not by the /usr/bin path.

On a plain debian or ubuntu base image the system Python is marked exactly as on a server. Create a venv in the image (python3 -m venv /opt/venv and ENV PATH="/opt/venv/bin:$PATH"); the pip guide has a full Dockerfile. Setting PIP_BREAK_SYSTEM_PACKAGES=1 in a single-purpose image is a judgement call: PEP 668 lets distributors leave the marker out of single-application images that are not updated after creation, but it still advises a venv there, because the application may call Python-based OS tools. Running containers is covered in docker run.

On a VPS: one venv or container per app

On a server, give each application its own venv (for example /opt/myapp/.venv) or its own container, and leave the system Python to apt. A systemd unit does not need activation; point it at the venv's interpreter:

systemd unit (excerpt)
[Service]
WorkingDirectory=/opt/myapp
ExecStart=/opt/myapp/.venv/bin/python app.py

The full unit file is in create a systemd service. Keep a requirements.txt next to the code: the Python docs call virtual environments disposable and not movable, and pyvenv.cfg records the interpreter it was built from (executable = /usr/bin/python3.11 on our server). After a release upgrade that changes the Python version, such as Debian 12 (3.11) to Debian 13 (3.13), delete the venv and recreate it from that file.

Confirm the fix

bash
. .venv/bin/activate
python -c "import sys; print(sys.prefix != sys.base_prefix)"   # True inside the venv
python -m pip --version     # the path should point into .venv
python -m pip install NAME  # no externally-managed error

If python3 itself is missing on the machine, start with python: command not found. The specification is PEP 668, and the venv module is documented in the Python docs.

Frequently asked

How do I fix error: externally-managed-environment?

Install into a virtual environment instead of the system Python: python3 -m venv .venv, then . .venv/bin/activate and pip install NAME. On Debian and Ubuntu install python3-venv first. For command-line tools use pipx install NAME, and for common libraries the distribution package python3-NAME.

Does pip install --user avoid the externally-managed error?

No. PEP 668 covers user installs as well as system-wide ones, so pip install --user stops with the same error on Debian 12, Ubuntu 23.04 and later and other marked systems. Use a virtual environment or pipx instead; neither needs root.

Is it safe to use --break-system-packages?

Only in a throwaway container or VM that nothing else depends on. It lets pip overwrite modules the distribution's package manager installed, and on Debian a root install lands in /usr/local/lib/python3.X/dist-packages, which is searched before apt's directory. The breakage then appears later in apt or system tools.

Why does pip work in the official python Docker image?

The official python images build Python from source into /usr/local and ship no EXTERNALLY-MANAGED file, so pip installs there directly. Images based on plain debian or ubuntu use the distribution's Python, which is marked, so create a venv in the Dockerfile.

Related articles

All troubleshooting