Python programming language logo displayed above the pip message, error externally-managed-environment.

Resolve Pip Error Externally Managed Environment

  • Adam Douglas

It is inevitable that as a computer user will experience error messages that does not entirely make sense. In particular when working with Python packages one may come across the message “error: externally-managed-environment”. What does this mean? What options does one have to resolve this problem? Let’s break this down and provide possible solutions to this issue, so you can continue on your merry way.

Environment

Tested using the following…

  • Arch Linux
  • Fish v3.6.1
  • GNU Bash v5.1.16
  • Python v3.11.3

Assumptions

  • Steps prefixed with a “$” (dollar sign) represents the CLI (command-line interface) prompt
  • Steps prefixed with a “#” (number sign) represents the CLI prompt with elevated user permissions (e.g. root)
  • The text after the “$” or “#” is to be entered at the CLI
  • A directory path that includes a “~” (tilde) expands automatically to the current user home directory (.e.g. /home/adamsdesk)

Problem

Each time a Python package is installed or uninstalled using pip the action is stopped with the following error message as illustrated below.

$ pip uninstall mkdocs

error: externally-managed-environment

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

    If you wish to install a non-Arch-packaged Python package,
    create a virtual environment using 'python -m venv path/to/venv'.
    Then use path/to/venv/bin/python and path/to/venv/bin/pip.

    If you wish to install a non-Arch packaged Python application,
    it may be easiest to use 'pipx install xyz', which will manage a
    virtual environment for you. Make sure you have python-pipx
    installed via pacman.

note: If you believe this is a mistake, please contact your Python
installation or OS distribution provider. You can override this, at
the risk of breaking your Python installation or OS, by passing
--break-system-packages.
hint: See PEP 668 for the detailed specification.

What Does This Mean?

The operating system configuration is protecting the user against having system provided packages (e.g. pacman, apt, dnf, etc.) and pip provided packages. Mixing the two different package managers is a bad idea and usually ends with having multitude of issues that no one desires.

Solution - Override

Danger

This method is not advisable, as this will most likely break system packages. 

$ pip install package-name --break-system-packages.

Another option to not have to add a command-line parameter would be to add the following to the user’s pip configuration file.

$ nano ~/.config/pip/pip.conf:

[global]
break-system-packages = true

Solution - Virtual Environment

The following example will create the Python virtual environment, and then it will be activated.

For further explanation on creating virtual environments and how they work read the Python documentation on venv - Creation of virtual environments.

$ python -m venv .venv
# source .venv/bin/activate

Tip

To manage and use virtual environments easier try using pipx (e.g. package name python-pipx, pipx).

Solution - Package Manager

Each system uses a different package manager, so exact steps will vary. Search for the desired package and then install the desired package.

$ pacman -Ss keyword

# pacman -Sy package-name

Tip

On an Arch Linux system an AUR Helper may be helpful in finding and installing the desired package.

References

Comments

Reply via email