error: externally-managed-environment (pip / PEP 668) — Fix

Q: What is the correct way to fix it?

For a project, create and activate a virtual environment: python3 -m venv .venv && source .venv/bin/activate, then pip install normally. For a standalone command-line app, use pipx install , which isolates each app in its own venv but exposes it on PATH.

Q: Should I use --break-system-packages?

Avoid it. pip install --break-system-packages overrides the protection and installs into the system Python, which is exactly what PEP 668 prevents — it can corrupt OS-managed packages and break your package manager. Use it only as a last resort in a throwaway container, never on a machine you care about.

Q: When is pip install --user a valid option?

On some systems pip install --user installs into your home directory and sidesteps the system site-packages, which may be allowed. But many PEP 668 distros also block --user, and it still pollutes a shared user environment. A venv or pipx is cleaner and more reliable.

Q: How do I install a package globally on Debian/Ubuntu the supported way?

Use the distro's own packages: sudo apt install python3- pulls a version the OS manages and won't conflict with pip. For anything not packaged, use a venv or pipx. Reserve apt for system integration and venv/pipx for everything else.

Q: Why did pip install stop working after upgrading to Ubuntu 24.04?

Ubuntu 23.04 introduced the PEP 668 EXTERNALLY-MANAGED marker and Ubuntu 24.04 LTS (system Python 3.12) enforces it by default, so a global pip install that used to work now errors. Nothing is broken — the OS is protecting its system Python. Install into a virtual environment (python3 -m venv .venv) or use pipx instead.

Quick answer

Your OS marked this Python as managed by apt / dnf / Homebrew, and under PEP 668 pip won't install into it — that could overwrite system files. The right fix is a virtual environment (python3 -m venv .venv) for projects, or pipx for command-line apps. Do not reach for --break-system-packages.

The exact error string

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

Why pip is refusing (PEP 668)

The distribution dropped an EXTERNALLY-MANAGED marker file beside the Python install. pip honors it and declines to touch the system site-packages, because OS tools depend on exact versions there — a pip install (or worse, pip install --upgrade) could replace them and break your package manager. The message isn't a bug to defeat; it's pointing you to an isolated environment.

Why this suddenly appeared on Ubuntu 24.04

If pip install worked for years and then started failing after an upgrade, PEP 668 is why. Ubuntu 23.04 was the first release to ship the EXTERNALLY-MANAGED marker, and Ubuntu 24.04 LTS (with its system Python 3.12) enforces it by default — which is when most people hit it, because 24.04 is the long-term-support release everyone upgraded to. Debian 12 (Bookworm), Fedora 38+, and recent Homebrew Python did the same thing around the same time. Nothing is broken on your machine; the distro simply started protecting its system Python. The fix is not to re-enable global installs — it's to move your packages into a venv or pipx, below.

Fix 1: a virtual environment (per project) — recommended

# create once, in your project folder
python3 -m venv .venv

# activate (Linux/macOS)
source .venv/bin/activate
# activate (Windows PowerShell)
# .venv\Scripts\Activate.ps1

# now pip installs into the venv, not the system
pip install requests
python app.py

Fix 2: pipx (for standalone CLI tools)

# install pipx once via your OS, then:
pipx install black
pipx install httpie

# each tool gets its own isolated venv but is on your PATH
black --version

Use pipx when you want a command available everywhere (linters, formatters, CLIs) without polluting any project or the system Python.

Fix 3: the distro package (for system integration)

# Debian / Ubuntu (incl. 24.04 LTS)
sudo apt install python3-requests

# Fedora
sudo dnf install python3-requests

# Arch Linux
sudo pacman -S python-requests

On macOS (Homebrew Python)

Homebrew's Python is externally managed too, so you'll see the same error. Use pipx for CLI tools and a venv for project code:

# install pipx once, then isolate CLI tools
brew install pipx
pipx ensurepath
pipx install black

# for a project, use a venv exactly as on Linux
python3 -m venv .venv
source .venv/bin/activate
pip install requests

What NOT to do

# ❌ defeats PEP 668 and can corrupt OS-managed packages
pip install requests --break-system-packages

# ❌ same risk, just louder
sudo pip install requests --break-system-packages

This overrides the exact protection PEP 668 added. Reserve it for a throwaway container you're about to delete — never a machine whose package manager you rely on.

Which fix should I use?

You want to...	Use	Command
install deps for a project	venv	`python3 -m venv .venv`
install a CLI tool globally	pipx	`pipx install <tool>`
integrate with system tools	distro pkg	`apt install python3-<name>`
throwaway container only	override	`--break-system-packages` (last resort)

Debugging checklist

✓ Working on a project? Create & activate a venv, then pip install
✓ Installing a CLI app? Use pipx install
✓ Need OS integration? apt/dnf install python3-<name>
✓ Prompt still shows the system Python? Confirm the venv is activated (which python)
✓ Resist --break-system-packages outside disposable containers

Frequently Asked Questions

What does 'error: externally-managed-environment' mean?

Your operating system marked this Python as managed by its own package manager (apt, dnf, Homebrew). Under PEP 668, pip refuses to install into it because doing so could overwrite files the OS owns and break system tools. The intended fix is to install into a virtual environment or with pipx instead.

What is PEP 668?

PEP 668 is the standard that lets a distribution mark an environment as "externally managed" by placing an EXTERNALLY-MANAGED marker file next to the Python install. pip honors that marker and declines system-wide installs, steering you toward isolated environments.

What is the correct way to fix it?

For a project, create and activate a virtual environment: python3 -m venv .venv && source .venv/bin/activate, then pip install normally. For a standalone command-line app, use pipx install <tool>, which isolates each app in its own venv but exposes it on PATH.

Should I use --break-system-packages?

Avoid it. pip install --break-system-packages overrides the protection and installs into the system Python, which is exactly what PEP 668 prevents — it can corrupt OS-managed packages and break your package manager. Use it only as a last resort in a throwaway container, never on a machine you care about.

When is pip install --user a valid option?

On some systems pip install --user installs into your home directory and sidesteps the system site-packages, which may be allowed. But many PEP 668 distros also block --user, and it still pollutes a shared user environment. A venv or pipx is cleaner and more reliable.

How do I install a package globally on Debian/Ubuntu the supported way?

Use the distro's own packages: sudo apt install python3-<name> pulls a version the OS manages and won't conflict with pip. For anything not packaged, use a venv or pipx. Reserve apt for system integration and venv/pipx for everything else.

Why did pip install stop working after upgrading to Ubuntu 24.04?

Ubuntu 23.04 introduced the PEP 668 EXTERNALLY-MANAGED marker and Ubuntu 24.04 LTS (system Python 3.12) enforces it by default, so a global pip install that used to work now errors. Nothing is broken — the OS is protecting its system Python. Install into a virtual environment (python3 -m venv .venv) or use pipx instead.

References

PEP 668 — Marking Python base environments as “externally managed” (python.org)
pip documentation (pypa.io)
Installing packages using pip and virtual environments — Python Packaging User Guide
pipx documentation (pypa.io)

More Python & tooling errors

Browse the full reference for Python, Node.js, Go, and database errors — exact message, cause, and fix.

All Error References Python: unexpected indent

About the author

Pasindu Ishan is a software developer based in Sri Lanka. He builds privacy-first developer tools at JSON Dev Tools.