Maaz Zindani

Loading the index…

↑↓ move↵ openesc close4072 pages
Servers, nginx and Docker

pip refuses to install: this environment is externally managed

Errorerror: externally-managed-environment

Short 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.

  • Applies to Python 3.12, pip 24, Ubuntu 24.04, pipx 1.x
  • Updated
  • By Maaz Zindani, Senior Software Engineer

Fix it fast

  1. 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)"
  2. 2Match what you see, then jump to its fix

    1. 1error: externally-managed-environment on pip install -r requirements.txtYou are installing a project's libraries into the system PythonFix
    2. 2The 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. 3The first message tells you to try apt install python3-xyzThe package exists as a distribution packageFix
    4. 4The failure is in a Dockerfile or a pipeline, and nothing else uses that PythonA throwaway container or CI job where isolation does not matterFix

What does the error look like?

  • error: externally-managed-environment
  • To install Python packages system-wide, try apt install python3-xyz
  • create 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.txt

3Verify

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

Did this fix it?

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 pipx

2Fix

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 black

3Verify

Open a new terminal, then run the tool.

black --version

Confirmed by pipx.pypa.io

Did this fix it?

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-requests

2Fix

Install the apt package instead of using pip, when the version it offers is enough.

sudo apt install python3-requests

3Verify

The system Python can import it.

python3 -c "import requests; print(requests.__version__)"

Confirmed by packaging.python.org

Did this fix it?

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-packages

2Fix

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 requests

3Verify

The install completes without the error.

pip show requests

Confirmed by pip.pypa.io

Did this fix it?

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:

Related fixes

Next step

Want this handled for good?

I look after servers, apps and releases end to end. Tell me what keeps breaking.