Is it safe to delete the EXTERNALLY-MANAGED file?

It removes the warning, not the risk. The file exists because the operating system's package manager owns that Python's packages; deleting it lets pip overwrite them again, and a system update can restore the file anyway. Use a virtual environment or pipx instead.

Does pip install --user avoid the error?

No. On distributions that adopt PEP 668, pip install --user fails with the same externally-managed-environment error, because user installs still affect the system interpreter. The pipx documentation states this for Ubuntu 23.04+, Debian 12+ and Fedora 38+.

Why don't I get this error inside a virtual environment?

The rule only applies outside virtual environments. The specification tells installers to check whether they are running inside one (by comparing sys.prefix with sys.base_prefix) and, if so, ignore the marker file. That is why creating a venv is the standard fix.

Does this error happen on Windows?

Not with the standard python.org installer, which does not ship the marker file. It appears where a system package manager owns Python: most current Linux distributions and Homebrew's Python on macOS.

Fix pip "error: externally-managed-environment" (PEP 668)

pip prints error: externally-managed-environment because your system Python belongs to the operating system's package manager, and pip has been told not to install into it. The fix is to install into a virtual environment (python3 -m venv .venv), use pipx install for command-line apps, or install the distro's package (sudo apt install python3-xyz).

The --break-system-packages flag the error mentions does work, but it is named that way on purpose. Use it only when none of the options below fit.

The full error message

This is pip 26.0.1's output with the sample Debian marker text from PEP 668. On a real system the paths and package hints match your distribution's version:

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.9/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.

The middle block comes from the distribution, not from pip. If the marker file contains no message, pip prints a generic one instead: The Python environment under ... is managed externally, and may not be manipulated by the user. Please use specific tooling from the distributor of the Python installation to interact with this environment instead.

Why distributions added it

On Linux, the system Python is not just for you. Tools that ship with the OS are written in Python and depend on specific versions of libraries installed by apt or dnf. When sudo pip install upgrades one of those libraries, the OS tools can break. PEP 668 gives a concrete case: it was "possible to unintentionally break Fedora's dnf command with a pip install command, making it hard to recover."

The mechanism is a single file named EXTERNALLY-MANAGED in the interpreter's standard library directory, such as /usr/lib/python3.9/EXTERNALLY-MANAGED in the PEP's Debian example. When pip runs outside a virtual environment and finds that file, the specification says it should stop with an error. The pipx docs list Ubuntu 23.04+, Debian 12+ and Fedora 38+ as distributions that adopt it, and Homebrew's docs say Homebrew "marks its current Python as externally managed according to PEP 668". You can see the path on your machine with:

python3 -c "import sysconfig; print(sysconfig.get_path('stdlib'))"

Fix 1: install into a virtual environment (for projects)

This is what the error itself recommends, and what PEP 668 calls a better solution for most use cases. Inside a venv, the marker file is ignored and pip installs normally:

python3 -m venv .venv
source .venv/bin/activate
python -m pip install requests

On Debian and Ubuntu, the error message says to make sure python3-full is installed; on Debian it depends on python3-venv, the package that provides the venv module:

sudo apt install python3-full

You can also skip activation and call the environment's interpreter directly, which is the better form for cron jobs and systemd services: .venv/bin/python -m pip install requests, then .venv/bin/python app.py. The full walkthrough, including Windows shells and requirements.txt, is in Python virtual environments (venv).

Fix 2: use pipx for command-line tools

If the thing you are installing is an application you run from the terminal (black, httpie, yt-dlp, poetry), you don't want a project venv for it. pipx creates a separate virtual environment for each app and puts its command on your PATH. Install pipx from the distribution, as its docs recommend on PEP 668 systems:

# Ubuntu 23.04 or newer
sudo apt update
sudo apt install pipx
pipx ensurepath

# Fedora
sudo dnf install pipx
pipx ensurepath

# macOS (Homebrew)
brew install pipx
pipx ensurepath

Open a new terminal so the PATH change applies, then:

pipx install black
black --version

Fix 3: install the distribution's package

If a library is packaged by your distribution and you need it for system-wide scripts, install it with the OS package manager. Debian and Ubuntu name Python libraries python3- plus the project name:

sudo apt install python3-requests

Search first with apt search python3- or dnf search python3-. The versions are often older than on PyPI, but they are tested against the rest of the system, which is the point.

Why --break-system-packages is a last resort

The pip docs describe the flag in one line: "Allow pip to modify an EXTERNALLY-MANAGED Python installation". PEP 668 asked that such an override "should not be enabled by default and should carry some connotation that its use is risky", hence the name. Using it brings back exactly the problem the marker prevents: pip can replace a library that an OS tool depends on, and the next apt upgrade can silently replace pip's version again.

Situations where it can be reasonable: a throwaway container image where nothing else uses the system Python, or a CI runner rebuilt for every job. Even there, a venv costs one extra line. Never combine it with sudo on a machine you care about.

Common variations

The error appears in a Dockerfile (for example on a debian:12 or ubuntu:24.04 base image): create a venv in the image and put its bin directory first on PATH, or start from an official python image, which compiles its own interpreter into /usr/local instead of using the distribution's.
You activated a venv but still see the error: the pip you ran is not the venv's. Run python -m pip --version; the path should be inside your .venv folder. If it isn't, the venv was not activated in this terminal.
pip install --upgrade pip fails with this error: don't upgrade the system pip. Upgrade pip inside your venv instead. Homebrew's docs say the same about its Python.

Frequently asked questions

Is it safe to delete the EXTERNALLY-MANAGED file?: It removes the warning, not the risk. The file exists because the operating system's package manager owns that Python's packages; deleting it lets pip overwrite them again, and a system update can restore the file anyway. Use a virtual environment or pipx instead.
Does pip install --user avoid the error?: No. On distributions that adopt PEP 668, pip install --user fails with the same externally-managed-environment error, because user installs still affect the system interpreter. The pipx documentation states this for Ubuntu 23.04+, Debian 12+ and Fedora 38+.
Why don't I get this error inside a virtual environment?: The rule only applies outside virtual environments. The specification tells installers to check whether they are running inside one (by comparing sys.prefix with sys.base_prefix) and, if so, ignore the marker file. That is why creating a venv is the standard fix.
Does this error happen on Windows?: Not with the standard python.org installer, which does not ship the marker file. It appears where a system package manager owns Python: most current Linux distributions and Homebrew's Python on macOS.