externally-managed-environment Python Origin: Application & API Last updated 13 Oct 2026

error: externally-managed-environment

Your system Python (Debian 12+, Ubuntu 23.04+, Homebrew) refuses pip installs into the OS-managed environment (PEP 668).

Exact message you may see This environment is externally managed
Explore the map of this error Full error map →
Seen on: Python

Meaning

Installing packages globally can break OS tools that depend on system Python. pip now blocks it and suggests a virtual environment.

Common causes

  • pip install outside a virtual environment on a PEP 668 system
  • Using sudo pip

⚡ Quick fix

  1. Create a venv: python3 -m venv .venv && . .venv/bin/activate
  2. Use pipx for CLI tools
  3. Install the apt package (python3-xyz) for system-wide libraries

Detailed fix by platform

Linux

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

How to diagnose

  1. Environment — Inside a venv?
  2. Tool — Is it a CLI app (use pipx)?

🔧 Still not fixed?

Many errors look alike. If the steps above didn’t solve it, one of these is probably what you’re facing:

Where this error sits

Origin: Application & API. Errors that are often confused with or caused by this one (click to open):

AttributeError — AttributeError: 'X' object has no attribute 'y' (Python)AttributeErrorConnectionRefusedError — ConnectionRefusedError: [Errno 111] Connection refused (Python)ConnectionRefusedErrorEvent loop is closed — RuntimeError: Event loop is closed (Python)Event loop is closedFailed building wheel — error: subprocess-exited-with-error / Failed building wheel for x (Python)Failed building wheelModuleNotFoundError — ModuleNotFoundError: No module named 'x' (Python)ModuleNotFoundErrornever awaited — RuntimeWarning: coroutine 'fetch' was never awaited (Python)never awaitedpip no matching distribution — ERROR: Could not find a version that satisfies the requirement x (from versions: none) (Python)pip no matching distr…externall…

Explore the map of this error Full error map →

🧠 Still stuck? Analyze your error

Paste the full message, response headers or stack trace — we'll detect the platform and point to the most likely cause.

💬 What worked for others

No tips yet — did something else fix this for you?

Share what worked for you

Tips are checked by an editor before they appear. Links are removed.