Photo by Taiki Ishikawa on Unsplash

You're setting up a new machine, or maybe you just upgraded to Ubuntu 23.04, or you're on a fresh Raspberry Pi install. You type the most normal command in the world — pip install requests — and Python throws a wall of red text at you that you've never seen before. You stare at it. You read it twice. And then you do what everyone does: you copy the error and Google it at 11pm wondering if you somehow broke your entire system.

I hit this for the first time on a Debian 12 box and honestly my first reaction was confusion. I've been running pip installs for years. Nothing changed on my end. But something definitely changed on Python's end, and the error message — while technically informative — doesn't exactly hold your hand through what to do next. The fix it suggests feels dangerous if you don't know what you're doing, and the alternatives aren't obvious at all.

Here's what's actually going on and how to get past it without torching your system's Python installation.

What the error actually looks like

error: externally-managed-environment

× This environment is externally managed
╰─> To install Python packages system-wide, see /usr/share/doc/python3.11/README.venv

    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.

    If you wish to install a non-Debian-packaged Python application,
    it may be packaged as a flatpak. See 'man installer(1)' for more
    information.

    If you are using a Snap package, see 'man snap-store(8)' for more
    information.

    Otherwise, to suppress this warning and install using pip anyway,
    use the flag:
      pip install --break-system-packages

note: If you believe this is a mistake, please contact your Python installation or OS distribution support channels for more information

hint: See PEP 668 for the technical background.

That --break-system-packages flag name is doing a lot of psychological work. Most people see it and immediately feel like they're about to do something catastrophic. Which, depending on context, you might be. But not always.

Photo by Bernd 📷 Dittrich on Unsplash

Why this started happening

This is PEP 668. It landed in Python 3.11 and basically gives operating systems a way to say "hey, this Python install is mine, back off." Debian, Ubuntu 23.04+, Raspberry Pi OS (Bookworm), and a bunch of others now ship with a marker file that tells pip the system environment is off-limits.

The reason makes sense when you think about it. Linux distros manage a ton of packages through apt that depend on specific Python package versions. If you go rogue with pip and upgrade something like urllib3 or cryptography system-wide, you can silently break apt, cloud-init, or half a dozen other system tools that were quietly depending on the old version. This has burned people badly enough that distro maintainers decided to just block it by default.

So the error isn't a bug. It's intentional. The question is just how to work around it in a way that doesn't come back to bite you later.

Photo by Jake Walker on Unsplash

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

This is the correct answer for basically any real project work. I know virtual environments feel like extra overhead when you just want to install one package and run a script. But they've saved me from dependency hell enough times that I don't even think twice anymore.

python3 -m venv ~/myenv
source ~/myenv/bin/activate
pip install requests

Once you're activated, pip works exactly like you remember. No flags, no warnings. And when you're done, deactivate drops you back out. The packages live in ~/myenv and don't touch anything system-level.

If you're on a machine where you're doing a lot of this, you can add a quick alias to your .bashrc or .zshrc so activating a default env is one command. Small thing, big quality of life.

Photo by David Pupăză on Unsplash

Fix 2: Use pipx for standalone tools

This one is underrated. If you're installing something like black, httpie, youtube-dl, or any other command-line tool — not a library for your code, but an actual tool you want to run — pipx is the answer.

sudo apt install pipx
pipx ensurepath
pipx install black

pipx creates its own isolated environment for each tool automatically. You get a clean global command without any of the system package pollution risk. And uninstalling is clean too, which is more than I can say for manually tracking what pip dropped into your PATH.

Fix 3: Use --break-system-packages (when you actually know what you're doing)

Look, sometimes you're on a throwaway container, a quick test VM, or you just genuinely need to install something system-wide and you know it won't conflict with anything. In that case, the flag is fine.

pip install requests --break-system-packages

But the name really is a warning. Use it on a production server running Debian and then wonder why apt starts acting weird six months later — that's on you. I've seen this exact scenario. Someone installs a package with the flag, forgets about it, and then six months of OS updates later something breaks in a way that takes two hours to trace back to a pip-installed package version conflict.

If you want to make this permanent (again, only do this if you know your environment), you can edit or create ~/.config/pip/pip.conf:

[global]
break-system-packages = true

I'd only do this on a dev machine that you control completely, not a shared system or anything that runs production workloads.

If none of that worked

Sometimes the venv approach fails because python3-venv isn't actually installed. Feels obvious in hindsight but it trips people up constantly.

sudo apt install python3-venv python3-full

Run that, then try the venv creation again. The python3-full package on Debian-based systems includes the stuff that sometimes gets left out of minimal installs. And if you're on a really stripped-down server image, you might also need python3-pip itself.

Also worth checking: are you accidentally running pip as root? If you're doing sudo pip install out of habit, stop. That's a separate problem that'll cause its own mess. Drop the sudo and use a venv.

The honest take

This error feels annoying when you first hit it, but honestly the people who implemented PEP 668 weren't wrong. System-level pip installs were always kind of a ticking time bomb — most of us just got lucky for a long time. Virtual environments are the right call for project work, pipx is great for tools, and the break-system-packages flag exists for the situations where you really know what you're doing.

The frustrating part is that the error message drops you four different suggestions including Flatpak and Snap, which are almost never what you want for Python packages. That section of the message could be a lot cleaner. But the core message is right: use a venv, protect your system Python, and move on.