The Error

You run pip install requests and get:

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.

This isn't a bug. Since PEP 668, operating systems like Ubuntu 23.04+, Debian 12+, Fedora and Homebrew's Python on macOS mark their system Python as "externally managed." pip now refuses to install packages into it, because doing so could break tools the OS itself depends on.

🎯 Quick Fix: Use a Virtual Environment

python3 -m venv .venv
source .venv/bin/activate          # Windows: .venv\Scripts\activate
pip install requests               # works now

That's the right fix for almost every project.

Why It Happens

flowchart TB SYS["System Python
/usr/bin/python3"] --> OS["OS tools depend on it
(apt, package managers, scripts)"] PIP["pip install into system Python"] -->|"could overwrite /
conflict with OS packages"| BREAK["💥 Broken system tools"] MARK["EXTERNALLY-MANAGED file
(PEP 668)"] -->|"pip refuses"| PIP VENV["Virtual environment
.venv/"] --> SAFE["✅ Project-only packages,
system untouched"]

The OS ships a marker file named EXTERNALLY-MANAGED in the Python installation. When pip sees it, it stops and tells you to use the OS package manager or a virtual environment.

Pick the Right Fix

You want to... Use Command
Install packages for a project venv python3 -m venv .venv && source .venv/bin/activate
Install a command-line tool (black, httpie, yt-dlp) pipx pipx install black
Do both, faster uv uv venv && uv pip install requests or uv tool install black
Get a package the OS provides apt / dnf sudo apt install python3-requests

Option 1: venv (projects)

cd my-project
python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt

On Debian/Ubuntu, if venv itself is missing: sudo apt install python3-venv.

Option 2: pipx (CLI tools)

pipx installs each tool in its own isolated environment and puts the command on your PATH.

sudo apt install pipx        # macOS: brew install pipx
pipx ensurepath
pipx install httpie

Option 3: uv (fast, modern)

curl -LsSf https://astral.sh/uv/install.sh | sh
uv venv                      # creates .venv
source .venv/bin/activate
uv pip install requests

Option 4: OS packages

Good for common libraries used by system scripts, but versions are often older than PyPI.

What About --break-system-packages?

pip install --break-system-packages requests
Avoid this on your own machine. The flag's name is the warning: it can overwrite packages your OS relies on, breaking tools in ways that are hard to debug. Only consider it inside throwaway containers where nothing else uses that Python.

In Docker, a cleaner approach is still a venv, or a Python base image (like python:3.12-slim) where pip works normally.

Common Situations

  • "I activated the venv but still get the error": check which pip. It should point inside .venv. Use python -m pip install ... to be sure you're using the venv's pip.
  • VS Code uses the wrong Python: run "Python: Select Interpreter" and choose .venv.
  • Jupyter can't find packages: install ipykernel inside the venv and select that kernel.
  • macOS with Homebrew Python: same fix: venv for projects, pipx for tools.

Checklist

  • Projects use a venv (or uv), never system Python
  • CLI tools installed with pipx or uv tool install
  • which python / which pip point where you expect
  • .venv/ added to .gitignore
  • --break-system-packages used only in disposable containers, if at all

Frequently Asked Questions

What does externally-managed-environment mean?

It means your Python installation is managed by the operating system or another package manager, such as apt or Homebrew. Under PEP 668, pip refuses to install packages there to avoid breaking system tools. Use a virtual environment, pipx or uv instead.

Is it safe to use --break-system-packages?

It's risky on a normal system, because pip may overwrite or conflict with packages the operating system depends on. It's generally only acceptable in isolated, disposable environments such as containers where nothing else depends on that Python installation.

Should I use pipx or a virtual environment?

Use pipx for standalone command-line tools you want available everywhere, like formatters or downloaders. Use a virtual environment for libraries your project's code imports. uv can handle both with uv venv and uv tool install.

Conclusion

pip's "externally-managed-environment" error is your OS protecting its own Python. Create a virtual environment for each project, use pipx or uv for command-line tools, and skip --break-system-packages unless you're in a disposable container.

Sources

Last verified: 2 November 2026.

Related reads: Fix Python ModuleNotFoundError · Fix Docker Permission Denied · How to Build an MCP Server in Python

I write practical guides for developers. Follow on LinkedIn or X, or invite me to speak.