If you've recently upgraded your Linux distribution (such as Ubuntu 23.04 or later) and tried to install a Python package globally using pip, you may have encountered a frustrating error message:
error: externally-managed-environment
This error is not a bug; it's a deliberate safeguard introduced by Python Enhancement Proposal (PEP) 668. Its purpose is to prevent users from accidentally breaking their operating system by modifying or deleting core Python packages that are managed by the system's native package manager (like apt or dnf).
While this is a necessary security measure, it can halt your development workflow. This guide will explain the cause of the error and provide the three most effective solutions, ranging from the best practice to the quick (but risky) fix.
Understanding the "externally-managed-environment" Error (PEP 668)
The core issue is a conflict of control. Your operating system relies on specific versions of Python packages for its own functionality. When you use pip install globally, you risk overwriting or removing these system-critical packages, leading to system instability or failure.
PEP 668 addresses this by adding a file named EXTERNALLY-MANAGED to the system's Python installation directory. When pip detects this file, it refuses to install packages globally, forcing you to use a safer method.
Solution 1: The Best Practice - Use a Virtual Environment (venv)
The recommended and most robust solution is to use a virtual environment. A virtual environment creates an isolated, self-contained Python installation for each project, allowing you to install, upgrade, and remove packages without affecting the global system or other projects.
The principle of isolation that makes virtual environments essential for Python development is equally critical for professional web operations like web scraping and data collection.