Photo by Hitesh Choudhary on Unsplash

So you're trying to install something simple. Maybe it's requests, maybe it's numpy, something you've installed a thousand times before. You type pip install requests and instead of the usual progress bar, you get this wall of red text that ends with "externally-managed-environment." And you just stare at it. What does that even mean?

I hit this for the first time on a fresh Ubuntu 23.04 box and honestly spent about 20 minutes convinced I'd broken something during setup. I hadn't. This is intentional behavior introduced in Python 3.11+ following PEP 668, and it's now showing up on Debian, Ubuntu, Fedora, and basically any distro that ships a system-managed Python. The first time it bites you, it feels like the system is being weirdly hostile. It kind of is, but for a reason.

What the error actually 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 path/to/venv.
    You may then execute the environment's bin/pip to install
    packages within it.

note: If you believe this is a mistake, please contact your Python
installation's distributor for guidance. You can override this,
but you should read the error message first.

hint: See PEP 668 for the actual reasoning behind this.

The exact wording shifts a bit depending on your distro, but that's the shape of it. Red. Verbose. Confusing if you've never seen PEP 668 before.

Photo by Gabriel Heinzer on Unsplash

Why this is happening to you now

Here's the thing. Your Linux distro uses Python internally for system tools. Package managers, update scripts, all sorts of stuff running under the hood. When you pip install something globally, you're dumping packages into the same Python environment those system tools depend on. You could accidentally upgrade a shared dependency and quietly break something your OS relies on.

So starting with Python 3.11, if a distro marks its Python install as "externally managed" — meaning the distro's own package manager owns it — pip will refuse to touch it without a fight. It's a guardrail. An annoying one when you just want to run a quick script, but a real one.

The EXTERNALLY-MANAGED file sitting at /usr/lib/python3.x/EXTERNALLY-MANAGED is literally what triggers this. That file existing is the signal. That's all it takes.

Photo by Mohammad Rahmani on Unsplash

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

This is the correct answer most of the time. Honestly. Virtual environments are not that much extra work and they save you from dependency hell later on. Here's the full flow:

# Create a virtual environment in your project folder
python3 -m venv venv

# Activate it
source venv/bin/activate

# Now pip works normally
pip install requests

Once you're inside the venv, pip installs packages into that isolated folder, not your system Python. The externally-managed error disappears completely because you're no longer touching the protected environment. And when you're done, just deactivate.

If you're running scripts regularly and don't want to activate a venv every single time, you can call the venv's Python directly:

venv/bin/python your_script.py

Clean. No activation needed. I do this constantly for quick automation stuff.

Photo by Lavi Perchik on Unsplash

Fix 2: The override flag (when you know what you're doing)

Sometimes you genuinely just need something installed globally and you accept the risk. Maybe it's a dev machine, maybe you're the only one using it, maybe you've thought it through. Fine. There's a flag for that:

pip install requests --break-system-packages

Yes, that flag name is deliberately scary. It's not subtle. The devs wanted you to know what you're opting into. But it works, and on a personal machine where you know what you're installing, it's totally reasonable.

You can also make this the default behavior so you don't have to type the flag every time. Edit or create your pip config:

# Create or edit ~/.config/pip/pip.conf
[global]
break-system-packages = true

After that, plain pip install whatever works again. I'd only do this on machines where you're the sole user and you know your way around Python dependencies. On a shared or production server? Don't.

Fix 3: Install via apt instead

This one gets overlooked but it's actually solid for common packages. Your distro's package manager knows about a lot of Python libraries and can install them in a way that plays nice with the system Python:

sudo apt install python3-requests
sudo apt install python3-numpy
sudo apt install python3-pip

The downside is you're stuck with whatever version the distro has packaged, which might be older. For cutting-edge stuff or specific version requirements, apt won't cut it. But for common tools? Works fine and zero conflicts.

Fallback tip if things got weird

If you already tried to force install something before finding this post and now your pip itself is acting strange, the fastest recovery is usually to delete the EXTERNALLY-MANAGED file entirely and reset. I don't love recommending that but sometimes it's just the fastest path back to sanity:

sudo rm /usr/lib/python3.x/EXTERNALLY-MANAGED

Replace 3.x with your actual Python version. Check with python3 --version first. Again — only do this if you genuinely understand what you're removing and you're on a machine you control. On anything production-facing, use the venv approach instead. Every time.

Wrapping up

Look, this error frustrated me too when I first saw it. But once you understand it's protecting your system Python from getting corrupted by random pip installs, it makes sense. Still annoying when you're in a hurry, but it makes sense.

The venv route is the clean answer. The --break-system-packages flag is the fast answer. Pick based on your situation. And if someone on your team hits this and panics thinking they broke their Python install — send them here, because they almost certainly didn't break anything.