error: externally-managed-environment
Your system Python (Debian 12+, Ubuntu 23.04+, Homebrew) refuses pip installs into the OS-managed environment (PEP 668).
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
- Create a venv: python3 -m venv .venv && . .venv/bin/activate
- Use pipx for CLI tools
- Install the apt package (python3-xyz) for system-wide libraries
Detailed fix by platform
Linux
python3 -m venv .venv && . .venv/bin/activate && pip install -r requirements.txt
How to diagnose
- Environment — Inside a venv?
- Tool — Is it a CLI app (use pipx)?
🧠 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.
Was this page helpful?
Report a correction or suggest an improvement
Last updated 2 Oct 2026