Fixing externally-managed-environment Error While Installing With pip

1. Introduction

Package managers are used to install, remove, and manage software packages, usually for a system or programming language. For instance, pip is the default package manager for the Python programming language. However, issues arise when another package manager is also in use for the same purpose.

In this tutorial, we learn how to fix the externally-managed-environment error when installing a package with pip.

We begin by learning what causes the externally-managed-environment error. Next, we talk about two methods of getting around this error.

The first method we go over uses the system package manager to install the package. Then, we go over a method using a virtual environment.

2. What Is the externally-managed-environment Error?

Installing a package globally with pip may cause package and version conflicts for systems that rely on python. For this reason, the externally-managed-environment error exists.

Let’s see this error in action by attempting pip install in Ubuntu:

$ pip install 'arrow'
error: externally-managed-environment
...

In essence, the externally-managed-environment error occurs when the system package manager is managing Python packages. To be more exact, this error arises when pip installs outside of a virtual environment and a marker file, EXTERNALLY-MANAGED, exists in Python’s stdlib directory:

$ ls /usr/lib/python3.11
..
enum.py
EXTERNALLY-MANAGED
filecmp.py
...

The stdlib directory contains the files making up the Python Standard Library. Usually, Python’s stdlib directory is located in /usr/lib/<python_version>.

Typically, systems requiring python prevent pip from installing packages globally with this method. Instead, we must install the Python package using the system package manager or a virtual environment.

3. Installing With apt

In most cases, the easiest method of getting around the externally-managed-environment error is installing the Python package using the system package manager.

In this section, we use apt on Ubuntu, but the process is similar for other distributions and system package managers.

Let’s begin by installing the arrow package. The name of the system package may be different than the one that pip uses. Therefore, we first attempt to identify the correct package:

$ apt list -v '*arrow*'
...
python3-arrow/lunar 1.2.3-1 all
    Python3 library to manipulate dates, times, and timestamps

In this example, we use apt with list ‘*arrow*’ to search for packages containing arrow in their name. Additionally, we use the -v flag to print information about the listed packages.

Typically, Python packages are named python3-<package> in Ubuntu. In this case, the package name is python3-arrow.

Next, we install python3-arrow using apt:

$ sudo apt install python3-arrow
...
Setting up python3-arrow (1.2.3-1) ...

Now, arrow is installed globally. A benefit to this method is that updating our system updates this package as well.

4. Installing With venv

While installing using the system’s package manager may be convenient, it also has its limitations:

• limited number of package versions available
• restricted amount of available packages
• less up-to-date packages
• inability to install from a requirements.txt file

To get around these restrictions, we can use venv to create a virtual environment.

4.1. Creating Virtual Environment

Let’s begin by installing venv:

$ sudo apt install python3-venv

Then, we can create our virtual environment:

$ python3 -m venv ~/myvirtualenv

In this example, we run python3 with -m venv to specify we want to run venv as a script. Then, we pass the directory to use for our virtual environment (~/myvirtualenv).

After this, we activate our virtual environment by running the activate script:

$ source myvirtualenv/bin/activate
(myvirtualenv) $

After activating our virtual environment, its name (directory of virtual environment) appears in the terminal before the prompt string ($). This is how we know our virtual environment is currently active.

4.2. Installing Packages in Virtual Environment

Finally, we can install the packages we need. Let’s first install arrow, this time using pip:

$ pip install 'arrow'
...
Successfully installed arrow-1.3.0

Notably, the version we installed with pip is more up-to-date than the one installed with apt. Usually, the system package manager holds back packages, but pip installs the latest version.

Now, let’s try installing from a requirements.txt file.

First, we add packages we want to into a requirements.txt, each separated by a newline:

$ echo 'url-normalize' >  requirements.txt
$ echo 'chess'         >> requirements.txt
$ echo 'requests'      >> requirements.txt

As we can see, our requirements.txt file now has the names of three packages to install.

Now, let’s install our packages with pip:

$ pip install -r requirements.txt

Once we’re done using our virtual environment, we can exit using deactivate:

$ deactivate

Once deactivated, the packages we installed are no longer accessible in our environment. However, we can access them again by reactivating the same virtual environment.

5. Conclusion

In this article, we went over what the externally-managed-environment error is. Then, saw how to overcome this error via two different methods.

We began by using the system package manager, apt, to install a Python package. Then, we did the same using pip in a virtual environment created with venv.