Photo by sang xiaolei on Unsplash

So there I was, setting up a fresh Ubuntu 23.04 machine, just trying to install a simple package with pip like I've done a thousand times. I ran pip install requests and instead of the usual download progress bar, I got slapped with this:

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 need.

    If you wish to install a non-Debian-packaged Python package,
    create a virtual environment using python3 -m venv path/to/venv.
    ...
    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 distribution, by passing --break-system-packages.

note: If you are using a virtual environment, the command would be pip install requests

I'll be honest — my first reaction was pure confusion. I've been using pip for years and this error just showed up out of nowhere on newer systems. Turns out this is a Python error that started appearing after PEP 668 was implemented, which basically tells pip to back off when the Python installation is managed by the OS package manager (like apt on Debian/Ubuntu). The idea is to prevent pip from stomping all over system Python packages and breaking things at the OS level.

Completely reasonable from a stability standpoint. Still annoying as heck when you just want to get something installed quickly.

Here's the thing though — depending on your situation, there are a few ways to handle this. Let me walk you through the ones I actually use.

Fix #1: Use a Virtual Environment (The Right Way)

Honestly, this is the correct fix if you're working on a project. Virtual environments exist for exactly this reason — they give you an isolated Python environment where pip can do whatever it wants without touching system packages.

# 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, that externally-managed-environment error just goes away. You'll see (venv) in your terminal prompt, which is your signal that you're in the isolated environment. When you're done, just run deactivate.

I've seen a lot of beginners skip this step and then wonder why their projects conflict with each other six months later. Virtual envs are annoying to set up once, and then you forget about it. Worth it.

Fix #2: Use the --break-system-packages Flag

Sometimes you're not working on a project — you just want to install a tool system-wide for personal use. Maybe it's a CLI utility or something you run ad-hoc. In that case, you can override the restriction by passing a flag that, yes, sounds scarier than it is for most use cases:

pip install requests --break-system-packages

This works fine for most packages. The risk the error message warns about is real but mostly applies to packages that conflict with OS-managed Python libraries. For standalone tools and common packages, you're probably fine. I use this on my personal dev machines all the time without issues.

That said, I wouldn't do this on a production server or anything where the OS Python environment actually matters. Use venvs there.

Fix #3: Remove the EXTERNALLY-MANAGED File (Nuclear Option)

Alright so this one is the sledgehammer approach. The entire restriction comes from a single file sitting in your Python installation directory. You can just... delete it.

# Find the file location (adjust Python version as needed)
ls /usr/lib/python3.11/EXTERNALLY-MANAGED

# Remove it
sudo rm /usr/lib/python3.11/EXTERNALLY-MANAGED

After that, pip goes back to behaving exactly like it used to — no errors, no warnings. This is genuinely useful if you're setting up a Docker container, a CI pipeline, or some environment where you specifically don't care about OS-level package management because you control the whole environment yourself.

In my experience, Dockerfiles are the most common place where this makes total sense. You're already in an isolated container — the whole point of that file doesn't apply.

# Example in a Dockerfile
RUN rm -f /usr/lib/python3.11/EXTERNALLY-MANAGED && \
    pip install -r requirements.txt

Just don't do this on your main workstation unless you really know what you're doing. You've been warned.

Fallback: Use pipx for CLI Tools

If what you're trying to install is a command-line tool — something like black, httpie, or youtube-dl — there's actually a better option than any of the above: pipx. It installs Python CLI apps in their own isolated environments automatically, without you having to think about it.

# Install pipx first
sudo apt install pipx
pipx ensurepath

# Then install any CLI tool
pipx install black

The tool becomes available globally in your terminal, but it's cleanly isolated under the hood. No conflicts, no externally-managed-environment errors, no drama. Honestly pipx is underrated — more people should be using it for this exact scenario.

Quick recap of when to use what: virtual env for project work, --break-system-packages for quick personal installs, delete the EXTERNALLY-MANAGED file for Docker/CI environments, and pipx for CLI tools. Pick the right one for your situation and you won't have to fight with this Python error again.

Hope this saves you the 45 minutes of Googling I wasted the first time I hit it.