pip refuses to install: this environment is externally managed
error: externally-managed-environmentShort answer
Your Linux distribution marked its system Python as managed by apt, so pip will not write into it (PEP 668). Do not fight it. Install the package in a virtual environment, install command-line tools with pipx, use the python3-xyz apt package, or as a last resort pass --break-system-packages.
Fix it fast
1Find out which cause you have
Check whether you are inside a virtual environment. The block only applies outside one, so if the prefix and base prefix are equal, you are on the system Python.
python3 -c "import sys; print(sys.prefix == sys.base_prefix)"2Match what you see, then jump to its fix
- 1
error: externally-managed-environment on pip install -r requirements.txtYou are installing a project's libraries into the system PythonFix - 2
The package ships a command (a linter, a downloader, a formatter) and you ran pip install on itYou want a command-line tool, not a libraryFix - 3
The first message tells you to try apt install python3-xyzThe package exists as a distribution packageFix - 4
The failure is in a Dockerfile or a pipeline, and nothing else uses that PythonA throwaway container or CI job where isolation does not matterFix
- 1
What does the error look like?
error: externally-managed-environmentTo install Python packages system-wide, try apt install python3-xyzcreate a virtual environment using python3 -m venv path/to/venv
Cause 1 of 4
You are installing a project's libraries into the system Python
1Check
The marker file EXTERNALLY-MANAGED sits in the standard library directory of the system interpreter. Installers are meant to refuse when they are not inside a virtual environment.
python3 -c "import sysconfig, os; print(os.path.exists(os.path.join(sysconfig.get_path('stdlib'), 'EXTERNALLY-MANAGED')))"2Fix
Create a virtual environment for the project and install with its own pip. The PEP advises having python3-full installed on Debian-style systems.
sudo apt install python3-full
python3 -m venv .venv
.venv/bin/pip install -r requirements.txt3Verify
The pip you run is the one inside the project folder.
.venv/bin/python -c "import sys; print(sys.prefix)"Confirmed by peps.python.org
Cause 2 of 4
You want a command-line tool, not a library
1Check
Applications do not need to share an environment with your code. pipx gives each one its own.
which pipx2Fix
Install pipx from apt, add its folder to PATH, then install the tool through it.
sudo apt update
sudo apt install pipx
pipx ensurepath
pipx install black3Verify
Open a new terminal, then run the tool.
black --versionConfirmed by pipx.pypa.io
Cause 3 of 4
The package exists as a distribution package
1Check
Debian and Ubuntu package many popular libraries as python3-<name>. Those versions are tested against the system Python.
apt-cache policy python3-requests2Fix
Install the apt package instead of using pip, when the version it offers is enough.
sudo apt install python3-requests3Verify
The system Python can import it.
python3 -c "import requests; print(requests.__version__)"Confirmed by packaging.python.org
Cause 4 of 4
A throwaway container or CI job where isolation does not matter
1Check
pip has an explicit option, --break-system-packages, that allows it to modify an EXTERNALLY-MANAGED installation. The PEP calls it a risky override.
pip install --help | grep -A1 break-system-packages2Fix
Prefer a venv in the image. Only if you accept the risk, pass the override flag for that one command, or set it through the environment variable.
pip install --break-system-packages requests
# or: PIP_BREAK_SYSTEM_PACKAGES=1 pip install requests3Verify
The install completes without the error.
pip show requestsConfirmed by pip.pypa.io
How do I stop it coming back?
- Make a .venv for every project and keep it out of git.
- Use pipx for tools you want on your PATH, so upgrades never touch your project libraries.
- Never run sudo pip install on a system Python.
- In Dockerfiles, create the venv once and put its bin folder on PATH.
Sources
How was this page made?
I drafted this page with AI assistance from the official documents listed under Sources. Every cause above names the document that confirms it. I have not reproduced this fix on a machine of my own yet, so read it as documented guidance, not a test report. Found a mistake? Tell me.
Which stack is behind this page?
Projects of mine built on the same technologies:
- stegnor.comMy company site: 804 pages from a Python and Jinja generator, with 15 free browser tools.
- MenuloA restaurant discovery platform in Germany, kept current by a Python ingestion pipeline.
- ShopGoAn e-commerce aggregator with a Python scraping engine behind its catalog, past 10K Google Play downloads.
Related fixes
Servers
pip install confluent-kafka fails because librdkafka/rdkafka.h is missing
pip stops while building confluent-kafka from source
The error means pip is compiling confluent-kafka from source, and the compiler cannot find the librdkafka C headers.
3 causes, each with a fixServers
cv2.imshow raises 'not implemented' because the wrong OpenCV package is installed
cv2.imshow() works in one environment and fails in another
The headless OpenCV packages are built without any GUI code, so cv2.imshow cannot open a window.
2 causes, each with a fixServers
pip install Cython succeeded, but the shell cannot find cythonize
a pip warning that a script was installed to a directory outside PATH
pip put the cythonize script in a folder your shell does not search.
3 causes, each with a fixServers
Django returns a 500 behind Gunicorn and the traceback is nowhere
The traceback shows locally with runserver but not under Gunicorn
With DEBUG set to False, Django's default logging does not print errors to the console.
2 causes, each with a fixServers
Docker build fails with apk: not found in a Python or Ubuntu image
/bin/sh: 1: apk: not found
apk is the package manager of Alpine Linux only.
2 causes, each with a fixServers
You cannot pip install packages inside an Ubuntu Docker container
error: externally-managed-environment
If pip is missing, install the python3-pip package with apt, in the same RUN as apt-get update.
3 causes, each with a fix