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

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

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

How to fix this error

Frequently asked questions

What does "How to fix 'externally-managed-environment' error in Python (PEP 668)" mean?

11 and adopted by Debian/Ubuntu) restricts pip from installing packages to the system Python. ). The error indicates you are trying to install globally instead of in a virtual environment or with --break-system-packages flag.

How do I fix "How to fix 'externally-managed-environment' error in Python (PEP 668)"?

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 causes "How to fix 'externally-managed-environment' error in Python (PEP 668)"?

Installing to system Python instead of virtual environment Python or OS enforcing PEP 668 isolation policy Using system Python directly (not in venv)

Is the "How to fix 'externally-managed-environment' error in Python (PEP 668)" error serious?

It is a medium-severity error — more of a blocker than a risk. The steps above resolve it.

Related errors

• How to fix 'ERROR: Failed building wheel for package' in Python

  How to fix 'ERROR: Failed building wheel for package' in Python

  MEDIUM

• pipenv.exceptions.VirtualenvException: No virtualenv has been created

  How to fix "pipenv.exceptions.VirtualenvException: No virtuale" in Python

  MEDIUM

• error: command 'gcc' failed with exit status 1

  How to fix "error: command 'gcc' failed with exit status 1" in Python

  MEDIUM

• pipenv.exceptions.RequirementNotFound: Could not find a version that matches

  How to fix "pipenv.exceptions.RequirementNotFound: Could not f" in Python

  MEDIUM

• ModuleNotFoundError: No module named 'pkg_resources'

  How to fix "No module named 'pkg_resources'" in Python

  MEDIUM

• ERROR: Could not install packages due to an OSError: [Errno 30] Read-only file system: '/usr/lib/python3/dist-packages'

  How to fix "Read-only file system" error when installing packages with pip

  MEDIUM

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)