Pip Install Error: Externally-Managed-Environment

What is "error: externally-managed-environment"?

The externally-managed-environment error in Python occurs when you attempt to use pip to install packages in a Python environment that is managed by an external system, such as an operating system package manager or a bundled Python environment inside a specific application. The message simply tells you that the package won’t be installed, modified, or removed in this environment.

Why does "error: externally-managed-environment" happen?

The externally-managed-environment error happens because certain Python-based environments impose restrictions to ensure system stability and avoid conflicts, preventing unauthorized modifications that could potentially disrupt the system or the application's functionality. 

For example, Linux operating system distributions like Fedora and Debian come together with Python pre-installed. Since there are no official Python releases for these environments, most users must use the built-in interpreter. Trying to install packages with pip will download them inside the global environment, which may conflict with existing system packages and cause unexpected errors and issues. Even worse, if you attempt to uninstall or upgrade a package, it may break the operating system’s functionality entirely, as you may accidentally remove a core component. 

The proposed solution to this problem – distributors can mark their Python interpreter as having its packages managed by means external to Python. Doing so tells tools like pip that it shouldn’t change the installed system packages in any way unless specifically overridden. Therefore, if you attempt to install a package globally, you’ll encounter an externally-managed-environment error.

Solutions how to fix "error: externally-managed-environment"

Dealing with the externally-managed-environment error can be frustrating, but there are several effective ways to navigate around it. Here are three solutions to help you install your desired Python packages without encountering this roadblock: use a virtual environment, use a system package manager, or force install.

Use a virtual environment

To overcome the externally-managed-environment error, creating and using a virtual environment is the main solution. A virtual environment isolates your Python setup from the system-wide Python installation, allowing you to install and manage packages without affecting the rest of the system. Here’s the step-by-step guide to setting up a virtual environment:

1. Make sure venv is installed. venv is installed. On some operating systems, you might need to install the venv module if you don’t have it. On Debian-based systems (like Ubuntu), you can do this with the following terminal tool command:

2. Create a virtual environment. Navigate to your project’s directory and create a virtual environment with this command (replace envname with a name of your choosing):

3. Run the virtual environment. Activate the virtual environment to start using it. The command differs based on your operating system:

Linux/macOS:

Windows:

4. Install a package using pip. Once your virtual environment is activated, you can safely install a package without facing the externally-managed-environment error. For example, install the requests library by running the following command:

5. Deactivate the virtual environment. When you’re done working in the Python virtual environment, deactivate it by running:

Following these steps will isolate your project from the system-wide Python installation. This helps avoid externally-managed-environment errors and ensures that your projects have consistent and safe environments. Each project can have its dependencies, irrespective of the global Python setup, thereby avoiding conflicts that may arise.

Install with the system’s package manager

Another effective way to avoid the error is to install the desired Python packages through the system's package manager instead of using pip. This approach ensures compatibility and avoids conflicts with the system’s Python environment.

1. Identify the package manager that your system uses. Here’s a list of the most common ones:

• Debian-based systems (ex. Ubuntu) – apt
• Red Hat-based systems (ex. Fedora) – yum or dnf
• macOS systems – brew

2. Next, update your package list to have the latest information about available packages:

Debian-based systems:

Red Hat-based systems:

macOS systems:

3. Search if the package is available for installation in the system’s repositories:

Debian-based systems:

Red Hat-based systems:

macOS systems:

4. Install the desired package using the package manager. The package might be named slightly differently than in pip. For example, to install requests:

Debian-based systems:

Red Hat-based systems:

macOS systems:

Using the system’s package manager to install Python packages helps maintain system stability and ensures that all dependencies are managed in a consistent manner. This method leverages the system’s package management capabilities to handle complex dependencies and integrate smoothly with other system components.

Force install

You can use pip with additional options to bypass the environment's restrictions and install packages without raising any errors. This method should be used cautiously as it can potentially disrupt the system's Python environment. Below are a few ways to perform a forced installation:

Before proceeding, be aware that forcing installations can lead to conflicts with system packages, potentially causing instability or breaking the system's Python environment. If you’re unsure what you’re doing, please use virtual environments or system package managers.

1. Use the --break-system-packages option. Recent versions of pip include the --break-system-packages option that tells pip to ignore the restrictions imposed by the environment.

2. Use the --user option. It will install packages in the user site directory. This avoids the need for administrative permissions and reduces the risk of affecting the system-wide environment.

3. Use the --ignore-installed option. This is an alternative method to force installation and can be combined with the --user option for additional safety.

4. Combine with sudo (proceed with caution). As a last resort, you can combine pip commands with sudo to force installations at the system level. This should only be done if absolutely necessary and with a full understanding of the potential consequences.

Summary

The externally-managed-environment error in Python arises when attempting to install packages in a system-managed environment, ensuring stability and avoiding conflicts. To overcome this, use a virtual environment to isolate your setup or install Python packages through the system's package manager. You may also choose to force install them, but that comes with its risks and should be handled carefully.

References

Externally managed environments – Python documentation

Python’s virtual environment overview

Package management in Ubuntu

Yum package manager

DNF package manager

Brew package manager

pip install command reference