Photo by Rubaitul Azad on Unsplash

You sit down, you type pip install requests like you've done a thousand times, and suddenly Python just... refuses. No warning, no migration path, just a wall of red text telling you the environment is "externally managed." I ran into this on a fresh Debian 12 install and honestly my first reaction was that I'd broken something. I hadn't. Python had just changed the rules on me.

This started rolling out hard in 2023 across Debian, Ubuntu 23.04+, Fedora, Arch, and a bunch of other distros. PEP 668 is the reason. It's a spec that tells pip to back off when the system Python is managed by the OS package manager. The idea is to stop pip from silently overwriting system packages and breaking things like apt or system tools that depend on specific library versions. Reasonable goal. Terrible timing if you just needed to install something quickly.

The thing is, this isn't a bug. It's intentional. And once you understand why, the fixes make a lot more sense. But if you're staring at a broken CI pipeline at 11pm, you don't care about the philosophy. You just want packages to install. So here's what's actually happening and how to get past it.

What the error looks like

$ pip install requests
error: externally-managed-environment

× This environment is externally managed
╰─> To install Python packages system-wide, use apt install
    python3-xyz, where xyz is the package you're trying to
    install.

    If you wish to install a non-Debian-packaged Python package,
    create a virtual environment using python3 -m venv.

    ...

note: If you believe this is a mistake, please contact your
Python installation's distributor for guidance. You can also
refer to the following webpage for more context:
https://peps.python.org/pep-0668/

The exact wording varies a bit by distro, but that "externally-managed-environment" line is the giveaway. If you see that, PEP 668 is what's blocking you.

Photo by Hitesh Choudhary on Unsplash

Why this is happening now

Before PEP 668, pip would happily install packages into your system Python with zero resistance. That sounds convenient until pip upgrades a shared library that apt also depends on, and suddenly your package manager is broken. I've seen this happen. It's not fun to debug at all.

Linux distros got tired of users filing bug reports that were actually caused by rogue pip installs, so they baked a marker file into the Python install. On Debian/Ubuntu it lives at /usr/lib/python3/dist-packages/EXTERNALLY-MANAGED. When pip sees that file, it stops. That's the whole mechanism. Surprisingly simple for something that caused so much confusion.

The distros want you using apt install python3-packagename for system-level stuff, and virtual environments for everything else. Which, honestly, is the right call. But it's a jarring change if you had scripts or habits built around bare pip installs.

Photo by Pankaj Patel on Unsplash

Fix 1: Use a virtual environment (the right way)

This is the solution you should actually use long-term. Virtual environments were always the correct answer for project dependencies. PEP 668 just made it mandatory instead of recommended.

# Create a venv in your project folder
python3 -m venv .venv

# Activate it
source .venv/bin/activate

# Now pip works normally
pip install requests

# When you're done
deactivate

Once you're inside a venv, pip doesn't see the EXTERNALLY-MANAGED marker and installs without complaint. Your system Python stays clean, your project dependencies are isolated, and you can nuke the whole .venv folder if something goes sideways without affecting anything else on the machine.

If you're running scripts in cron jobs or something non-interactive, use the venv's pip directly:

/path/to/your/project/.venv/bin/pip install requests

Slightly verbose but completely predictable.

Photo by Markus Spiske on Unsplash

Fix 2: The --break-system-packages flag (use carefully)

Sometimes you genuinely need a package system-wide and you know what you're doing. There's an escape hatch:

pip install requests --break-system-packages

That flag explicitly tells pip "yes I understand, install it anyway." It works. But the name is not subtle. You are taking on the risk that pip might conflict with something apt is managing. In my experience this is fine for tools like pipx-style utilities where you're not touching core libraries, but I wouldn't do it for something with a deep dependency tree.

You can also make it permanent in your pip config if you want to stop typing the flag every time, though honestly I'd think twice before doing this on a machine you care about:

# Add to ~/.config/pip/pip.conf
[global]
break-system-packages = true

Fix 3: Use pipx for standalone tools

If what you're actually installing is a CLI tool like black, httpie, ansible, or anything you want available system-wide as a command, pipx is the answer. It creates an isolated venv per tool automatically, so you get the global command without the system pollution.

# Install pipx first (this one uses apt intentionally)
sudo apt install pipx
pipx ensurepath

# Then install tools with it
pipx install black
pipx install httpie

After that, black and http are available everywhere in your shell, each living in their own little sandbox. It's a genuinely good workflow once you get used to it. Way better than the old "pip install -g" that pip never actually had.

Fallback: delete the marker file (seriously don't)

You'll see people online suggesting you just delete /usr/lib/python3/dist-packages/EXTERNALLY-MANAGED. That makes the error go away permanently. It also throws away the protection the distro put there for good reasons. If you're on a throwaway container or a dev VM you rebuild constantly, maybe fine. On anything you want to stay stable? I'd avoid it. You're one bad pip upgrade away from a broken apt and a confusing afternoon.

The quick version if you just need it working

Honestly, the mental model shift is this: system Python is now the OS's Python. Your Python lives in a venv. Once that clicks, PEP 668 stops feeling like an obstacle and starts feeling like it's just... enforcing what was already best practice.

If you hit this mid-project and don't have time to restructure anything, --break-system-packages gets you unblocked. But do yourself a favor and migrate to venvs properly when you get a few minutes. Your future self dealing with a production incident won't have to wonder why pip and apt are fighting each other, and that's worth something.