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.
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 systemThe 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:
$ 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=1Four 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, andpip uninstallruns the same check. Exit status 1, no files touched. - The middle block is the distribution's text. pip prints the
Errorkey of the marker file, so Ubuntu, Alpine and Homebrew show different advice under the same first line. PEP 668 also allows translated keys such asError-de_DE, picked by your locale. - A venv switches it off. pip skips the check when
sys.prefixdiffers fromsys.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.
sudodoes not get past it, and neither does--user(see below).
Which systems mark their Python as externally managed
| System | Marked? | Marker file | Source |
|---|---|---|---|
| Debian 12 bookworm | Yes, since python3.11 3.11.2-3 (Feb 2023) | /usr/lib/python3.11/EXTERNALLY-MANAGED | Debian 12 release notes, package changelog |
| Debian 13 trixie | Yes | /usr/lib/python3.13/EXTERNALLY-MANAGED | packages.debian.org file list |
| Ubuntu 23.04 | Yes | /usr/lib/python3.11/EXTERNALLY-MANAGED | Launchpad changelog of python3.11 |
| Ubuntu 24.04 and later | Yes | /usr/lib/python3.12/EXTERNALLY-MANAGED (python3.14 on 26.04) | packages.ubuntu.com file lists |
| Ubuntu 22.04 | No | none in libpython3.10-stdlib | packages.ubuntu.com file list |
| Alpine 3.19 and later | Yes | in the stdlib directory | Alpine 3.19.0 release notes |
| Homebrew Python (macOS) | Yes | in the stdlib directory | Homebrew documentation |
| Official python Docker images | No | Python is built from source into /usr/local | docker-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:
$ 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)"
FalseTrue 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 to | Use | Command |
|---|---|---|
| install libraries for your own code | a virtual environment | python3 -m venv .venv |
| run a command-line tool from PyPI | pipx | pipx install NAME |
| give a system script a common library | the distribution package | sudo apt install python3-NAME |
| reuse apt packages plus a few from PyPI | a venv with system packages | python3 -m venv --system-site-packages .venv |
| override the guard in a throwaway container | the override flag | pip 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:
$ 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:
sudo apt install pipx
pipx ensurepath # adds ~/.local/bin to PATH; open a new shell afterwards
pipx install NAMEOn 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):
$ 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:
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 = trueOne 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:
[Service]
WorkingDirectory=/opt/myapp
ExecStart=/opt/myapp/.venv/bin/python app.pyThe 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
. .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 errorIf 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.