Problem: pip install fails with "externally-managed-environment" on new Ubuntu/WSL —— Trove problem library

What you will run into

On a fresh Ubuntu (or WSL), pip install of any package fails immediately with error: externally-managed-environment — even pip install numpy won't install.

You think Python 3.14 is too new, or pip is broken, or you even consider downgrading Python — none of that is it: this is the distro's default security policy, and pip is simply refusing, per the rules, to install into the system environment.

Why this happens

Ubuntu 23.04+ enables PEP 668 by default: the system Python is marked "externally managed", and pip refuses to install third-party packages directly into the system environment, preventing third-party packages from overwriting apt-managed system packages and breaking system Python.

• The error is unrelated to the Python version; it triggers for any package, at any time — this is designed behavior.
• The right fix isn't bypassing the check, it's using a virtual environment: venv is an isolated environment where pip can install freely without polluting the system.

PEP 668 is an "environment ownership" declaration: the system Python's site-packages are owned by apt/distro package managers, and pip writing directly would desync from apt's records (apt does not know what pip installed and may overwrite it on upgrade;

pip does not know what apt changed).

Distros declare ownership via a marker file (EXTERNALLY-MANAGED), and pip refuses when it detects it.

Deterministic takeaway: externally-managed-environment has nothing to do with the package name or version — it is about the target environment;

the fix is changing the environment, not bypassing it (--break-system-packages is an explicit "I know I will dirty the system" statement, fine only for containers/disposable environments); venv never triggers this because it has its own site-packages and is not marked externally-managed;

the fixed path is: python3 -m venv .venv first, then pip — do not fight the system Python.

Step by step

1. Create the virtual environment — Required

python3 -m venv .venv

If it reports ensurepip is unavailable, install it first: sudo apt install python3-venv (common on slim images).

2. Activate — Required

source .venv/bin/activate

After activation a (.venv) appears before the prompt, and pip now points into the venv (measured: pip install six inside the venv succeeds directly).

3. Install normally — Required

pip install -r requirements.txt

From now on, source .venv/bin/activate before working in the project and you'll never hit PEP 668 again.

4. Use pipx for CLI tools (optional) — Advanced

Prefer pipx install <app> for system-level CLI apps — pipx automatically creates an isolated venv per app, doesn't touch system Python, and doesn't hit PEP 668.

How to confirm it works

source .venv/bin/activate && pip install six && python -c "import six; print(six.__version__)"

No more externally-managed-environment and a successful import means it's fixed (measured: install succeeded inside the venv; the dry-run --break-system-packages path also verified, outputting Would install six-1.17.0).

Other environments

Symptom

On Ubuntu/Debian (including a fresh WSL Ubuntu 26.04), pip install <pkg> fails immediately:

error: externally-managed-environment
× This environment is externally managed
╰─> To install Python packages system-wide, try apt install ...

Installing any package fails, regardless of project dependencies (even pip install numpy fails); it is easy to misread as a Python 3.14 version issue and to consider downgrading Python.

Cause

Debian-family systems such as Ubuntu 26.04 enable PEP 668 by default: the system Python is marked "externally managed" and pip refuses to install third-party packages into it, preventing third-party packages from overwriting apt-managed system packages and breaking system Python. This is not a Python 3.14 bug but the distro default policy (enabled by default since Ubuntu 23.04).

Solution

1. Long-term (recommended): create a virtual environment, then normal pip install works again:

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

Note: if it reports a missing ensurepip, run sudo apt install python3-venv first (common on slim images).

1. Temporary bypass (one-off): pip install <pkg> --break-system-packages — skips the PEP 668 check; may overwrite system packages and conflict with apt, not recommended long-term.
2. System-level / CLI tools: prefer apt install python3-<pkg>; for command-line apps use pipx install <app> (pipx manages its own isolated venv).