How to fix How to fix 'externally-managed-environment' error in Python (PEP 668) in Python

PythonINTERMEDIATEMEDIUM

Modern Python (3.11+) and some Linux distributions prevent pip from installing packages globally to avoid conflicts with system package managers. You must use a virtual environment or install with appropriate flags.

What this error means

PEP 668 (introduced in Python 3.11 and adopted by Debian/Ubuntu) restricts pip from installing packages to the system Python. This prevents conflicts between pip packages and OS package managers (apt, yum, etc.). The error indicates you are trying to install globally instead of in a virtual environment or with --break-system-packages flag.

Typical symptoms

pip install fails with 'externally-managed-environment'
Error message mentions 'PEP 668'
Works with virtual environment but fails globally
Appears on Ubuntu 23.04+, Debian 12+, or Python 3.11+
Running with sudo doesn't help
Works with older Python versions
Per-user install (--user) may work as workaround

Common causes

Installing to system Python instead of virtual environment
Python or OS enforcing PEP 668 isolation policy
Using system Python directly (not in venv)
Package manager locked system Python
Debian/Ubuntu/Fedora policy preventing global pip installs
Upgrading to Python 3.11+ or new OS version
Development environment not set up with virtualenv

How to fix this error

1Verify the root cause

Review the error message above and identify which cause applies to your situation. Run additional diagnostics if needed.

2Apply the appropriate fix

Follow the corresponding solution from the causes section above.

3Retry the installation

Once you've addressed the root cause, try running 'pip install' again.

Related errors

Official resources & further reading

📚Python Official Documentation
📖
PEP 668: Excluding system packages(Official Docs)
💬
SO: externally-managed-environment error(Stack Overflow)
🐙
GitHub: pip issues(GitHub)