Photo by Taiki Ishikawa on Unsplash

So you're trying to install something with pip, totally routine stuff, and out of nowhere Python just refuses. No package installs. Just a wall of red text telling you your environment is "externally managed." I ran into this for the first time on a fresh Ubuntu 23.04 machine and I genuinely thought I'd broken something during setup. Spent about 20 minutes second-guessing my Python install before I figured out what was actually going on.

The frustrating part is that this error is intentional. Python isn't broken. It's doing exactly what it was told to do. That doesn't make it less annoying when you just want to install requests or numpy and move on with your life, but at least once you understand it, the fix takes about two minutes.

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 wish 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 can then use path/to/venv/bin/pip install package-name
    to install the package in the venv, avoiding this error.

    The externally-managed-environment error is defined in PEP 668,
    which you can read here: https://peps.python.org/pep-0668/

note: If you believe this is a mistake, you can override this
      by using --break-system-packages.
hint: See PEP 668 for the details.

Sound familiar? Yeah. It shows up on Ubuntu 22.04+, Debian 12, and pretty much any modern Linux distro that ships with Python 3.11 or higher. Also hits people on macOS using Homebrew's Python. The error message is actually pretty informative once you're not panicking, which I was.

Photo by Lavi Perchik on Unsplash

Why this is happening to you

Here's the thing: your operating system uses Python internally. Package managers, system scripts, update tools — a lot of that machinery runs on the system Python installation. Before PEP 668, nothing stopped pip from walking in and overwriting a library that your OS was quietly depending on. And when that happened, things broke in spectacular and confusing ways. Not fun to debug at 11pm.

So starting with Python 3.11, distros started shipping a marker file that tells pip "hey, hands off, this Python is managed by the system package manager." The file lives at something like /usr/lib/python3.x/EXTERNALLY-MANAGED. That's it. That's the whole mechanism. Pip sees that file, stops, and throws the error you're staring at.

It's honestly the right call from a system stability standpoint. But it catches people off guard, especially if you've been using pip the same way for years and suddenly it just stops working on a new machine.

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

This is genuinely the correct answer for almost every situation. I know it feels like extra steps but it takes like 45 seconds and you only do it once per project.

# Create the virtual environment
python3 -m venv myenv

# Activate it
source myenv/bin/activate

# Now pip works totally normally
pip install requests

Once you're inside the venv, pip does whatever you want. No errors. No drama. And you're not touching the system Python at all, which means your OS stays happy. When you're done working, just run deactivate. The venv folder sits in your project directory and you never have to think about it again until you need to delete it.

If you're doing this a lot, pipx is also worth knowing about for installing command-line Python tools globally without any of this headache.

Fix 2: Use the --break-system-packages flag

Look, sometimes you just need to install something fast and you're not working on a project with any real stakes. Maybe it's a personal machine, maybe you're testing something throwaway. In that case:

pip install requests --break-system-packages

That flag tells pip to override the externally-managed check and install anyway. It works. The flag name is designed to make you pause and think, which I respect. It's not subtle. You're explicitly saying "yes I know what I'm doing here." The risk is real — if you accidentally overwrite a library version that your system depends on, you can end up with weird behavior that's genuinely hard to trace back to a pip install you ran three weeks ago.

I'd only do this on a machine I'm prepared to reinstall or one that's completely isolated, like a Docker container or a dev VM.

Fix 3: Delete the EXTERNALLY-MANAGED marker file

This is the nuclear option and I'm including it because people do it and you should know the tradeoffs. You can just remove the file that triggers the check:

# Find it first
python3 -c "import sys; print(sys.prefix)"

# Then look in that directory
ls /usr/lib/python3.11/

# Remove the marker (you'll need sudo)
sudo rm /usr/lib/python3.11/EXTERNALLY-MANAGED

After that, pip behaves exactly like it used to before all this. No flags, no virtual environments required. But you've also permanently disabled the protection on that system. On a dedicated server where you control everything and you know exactly what's installed, maybe fine. On a general-purpose laptop that you care about? I wouldn't.

Fallback if pip itself is the problem

Occasionally the error shows up because pip is out of date or misconfigured, not because of the EXTERNALLY-MANAGED file specifically. If none of the above is working the way you expect, try running pip through the module directly:

python3 -m pip install --upgrade pip
python3 -m pip install requests --break-system-packages

Also worth checking: if you have multiple Python versions installed, make sure the pip you're calling actually matches the Python you think it does. Run which pip and which python3 and make sure they're pointing at what you expect. I've wasted embarrassing amounts of time installing packages into the wrong Python entirely.

Honestly, if you're going to be doing any serious Python work, just get in the habit of creating a venv for every project. It takes almost no time, it solves this problem permanently, and it also means your project dependencies stay isolated from each other. That alone has saved me from dependency hell more times than I can count. The externally-managed-environment error is annoying the first time you see it, but it's trying to help you. Sort of.