Fixing the “Externally Managed Environment” Error When Installing Python Packages on Linux

Last update: 10-25-2024

If you’re trying to install a Python package using pip and encounter the following error:

error: externally-managed-environment

× This environment is externally managed
╰─> To install Python packages system-wide, try apt install
    python3-xyz, where xyz is the package you are trying to
    install.

then you’re not alone. This issue is becoming increasingly common on Linux distributions, including Ubuntu, due to adherence to PEP 668.

Understanding the Issue: PEP 668

PEP 668 is a Python Enhancement Proposal that aims to make Python package management on Linux distributions more predictable and secure. When a Linux distribution follows PEP 668, the Python environment is marked as “externally managed.” This means users are restricted from installing packages directly with pip to prevent system instability.

Instead, the error suggests using the system package manager (e.g., apt on Ubuntu) to install packages. However, if you want to manage packages independently without affecting system-wide Python libraries, you can create a virtual environment.

Solution: Using a Python Virtual Environment

By creating a virtual environment, you can safely install Python packages with pip without impacting the system’s Python configuration. Here’s how:

1. Install the virtual environment package: First, make sure python3-venv is installed. Run:

   sudo apt install python3-venv

2. Create a virtual environment: In your project directory, create a virtual environment by running:

   python3 -m venv .venv

3. Activate the virtual environment: Activate it with:

   source .venv/bin/activate

4. Install your package: Now, you can use pip to install packages without issues:

   python3 -m pip install package-name

By using a virtual environment, you avoid conflicts with the system Python and stay compliant with PEP 668. It’s a straightforward and effective way to manage project-specific dependencies in a Linux environment.

Conclusion

The “externally managed environment” error can seem like an obstacle, but creating a virtual environment is a simple and safe solution that allows you to continue using pip as usual. Next time you encounter this issue, just follow these steps, and you’ll be up and running in no time.