How do I solve "error: externally-managed-environment" every time I use pip 3?

Question

When I run pip install xyz on a Linux machine (using Debian or Ubuntu or a derived Linux distribution), I get this 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.

    If you wish to install a non-Debian-packaged Python package,
    create a virtual environment using python3 -m venv path/to/venv.
    Then use path/to/venv/bin/python and path/to/venv/bin/pip. Make
    sure you have python3-full installed.

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

    See /usr/share/doc/python3.11/README.venv for more information.

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 error mean? How do I avoid it? Why doesn't pip install xyz work like it did before I upgraded my system using sudo apt upgrade?

Answer 1

I just faced this problem after using the same setup for years without ever seeing this problem. I use conda, and I was trying to install a package from inside a virtual (conda) environment. But I was seeing this error.

As I was already inside a virtual environment, solutions in that line were moot.

I did not want to use --break-system-packages flag or remove the EXTERNALLY-MANAGED file as either could invite further trouble.

So, when I ran which pip and which pip3, I got /usr/bin/pip and /usr/bin/pip3 respectively. Thus, I was sure that it was not the pip of the conda environment.

So, I did conda install pip, and my problem was solved.

It was probably caused by my removing many old conda environments and cleaning them with conda clean -a.

Answer 2

Suggestion: Do this only if your default python is not the system-wide GNU/Linux python

In my case, instead of python 3.12 of Ubuntu 24.04, I use python 3.10 of uv as default.

To find out which python3/pip3 you're using:

>>> which python3
/home/antioch/.local/share/uv/python/cpython-3.10.12-linux-x86_64-gnu/bin/python3
>>> which pip
/home/antioch/.local/share/uv/python/cpython-3.10.12-linux-x86_64-gnu/bin/pip3

After finding the python path go to the lib/python3.x folder

cd ~/.local/share/uv/python/cpython-3.10.12-linux-x86_64-gnu/lib/python3.10

Here remove the EXTERNALLY-MANAGED file.

rm EXTERNALLY-MANAGED

Since this is not your system python, it's safe to use.

Answer 3

Currently, some of the most upvoted answers are teaching you ways to ignore this problem. This is like telling you to take painkillers to stop feeling the pain of broken glass in your throat, rather than telling you to stop eating broken glass. Stop eating broken glass. There are much better ways to install packages from PyPI than using the --break-system-packages flag, or worse, deleting the EXTERNALLY-MANAGED file.

The error is telling you that the environment is externally managed. Your Debian distribution already handles installation of Python libraries using APT. For example, if you wanted to install the requests Python library, you can run:

sudo apt install python3-requests

These files get installed in /usr/lib/python3/dist-packages/, as you can see from the output of the dpkg -L command:

$ dpkg -L python3-requests
/usr/lib/python3/dist-packages/requests
/usr/lib/python3/dist-packages/requests/__init__.py
/usr/lib/python3/dist-packages/requests/__version__.py
/usr/lib/python3/dist-packages/requests/_internal_utils.py
# ...

If you run pip install requests, where should the files be installed? Should they be installed in /usr/lib/python3, or ~/.local/lib/python3/site-packages/ or somewhere else? The version installed from PyPI using pip might not be the same version included in the Debian package. What if the overwrite doesn't succeed? What if you have two requests packages installed system-wide? Should pip learn how to uninstall APT packages? You probably have hundreds of Debian packages that depend on Python; what if one of them breaks because of these conflicting versions of requests? Can you easily undo the pip installation? Will you even realise that the weird errors you are experiencing when you launch gedit or something are because of this? This seems like a recipe for disaster. You used to be able to use pip to install Python packages system-wide, and it caused so many problems that it now throws this error message instead.

So, what can you do instead?

1. Install packages using APT

You can install Python packages system-wide using APT. For example, you can install requests like this:

sudo apt install python3-requests

This version might not be the latest version found in PyPI. And not all packages on PyPI have been packaged for the Debian repositories. But fear not; there are other solutions.

Or: 2. Use pip in a virtual environment

If you haven't yet learned a tool to set up a virtual environment, I highly recommend it. All Python programmers should learn one. I recommend venv or virtualenv to beginners. To install venv, run:

sudo apt install python3-venv

Then create a virtual environment in your project directory like this:

python3 -m venv .venv

Now activate your virtual environment by running:

source .venv/bin/activate

This modifies your PATH environment variable to include .venv/bin/. Now you can install PyPI packages using pip into your virtual environment (in this case .venv/), like this:

pip install requests

If you don't want to activate and deactivate virtual environments, you can run pip and python directly from the virtual environment, like this:

$ .venv/bin/pip install requests
$ .venv/bin/python
>>> import requests

Or: 3. Use pipx

pipx is a great tool for installing command-line applications straight from PyPI. To install pipx, run:

sudo apt install pipx

Make sure ~/.local/bin/ is in your PATH environment variable, by running this command:

pipx ensurepath

Close your terminal and open it again for the changes to take effect.

Now you can install a command-line application from PyPI. Behind the scenes, pipx will set up a virtual environment for each application, with its dependencies, completely isolated from the rest of the system to prevent problems. It's brilliant. Here's an example:

$ pipx install ruff
$ ruff --help

Or: 4. Pass --break-system-packages

If you absolutely must eat broken glass, then you can pass the --break-system-packages option, like this:

pip install --break-system-packages requests

Never remove or rename /usr/lib/python3.12/EXTERNALLY-MANAGED. It is there to stop you from breaking your system. You may not notice that your system is broken until weeks or months later, and you won't understand at that point why it broke. If you must ignore these protections, you can do it on a one-off basis using --break-system-packages.

Answer 4

Set this environment variable in your shell (for example, Bash):

export PIP_BREAK_SYSTEM_PACKAGES=1

Or write it in your Dockerfile:

ENV PIP_BREAK_SYSTEM_PACKAGES 1

Reference: Python 3.11, pip and (breaking) system packages

Answer 5

Similar to other answers, I set the break-system-packages flag for running in a Docker container. But I suggest doing it with pip and avoid trying to figure out where pip.conf is. After installing pip, run:

python -m pip config --global set global.break-system-packages true

Answer 6

I ran into it while trying to install numpy in a google/cloud-sdk docker image. E.g.:

$ docker run --rm -it google/cloud-sdk:477.0.0-alpine
/ # apk add py3-pip
/ # pip install numpy
<the externally managed message>

To overcome this I did:

$ docker run --rm -it google/cloud-sdk:477.0.0-alpine
/ # apk add py3-pip
/ # python -m venv env
/ # env/bin/pip install numpy
/ # export PYTHONPATH=/env/lib/python3.11/site-packages

PYTHONPATH adds the directory where /env/bin/pip installs packages (/env/lib/python3.11/site-packages) to the search path.

And judging from the gcloud compute ssh INSTANCE output it worked. Without numpy it says:

WARNING:

To increase the performance of the tunnel, consider installing NumPy. For instructions, please see https://cloud.google.com/iap/docs/using-tcp-forwarding#increasing_the_tcp_upload_bandwidth

Or the other way to confirm this:

/ # python -c 'import numpy'

You can find the resulting image in the following gist.

Answer 7

I had this problem while trying to use pip from inside a virtual environment on Python 3.12.

Probably some guardrail to avoid installing packages on system-wide python by mistake (throw the first rock the one who never did it before).

So after loading your venv

source venv/bin/activate

you should use your pip by pointing to the venv directory or by using the activated python with the module flag

./venv/bin/pip install xyz
# or
python3 -m pip install xyz

Answer 8

I was trying to install virtualenv and virtualenvwrapper to a fresh Linux Mint 22 with pip:

sudo pip3 install virtualenv
sudo pip3 install virtualenvwrapper

and I got this 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.

    If you wish to install a non-Debian-packaged Python package,
    create a virtual environment using python3 -m venv path/to/venv.
    Then use path/to/venv/bin/python and path/to/venv/bin/pip. Make
    sure you have python3-full installed.

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

    See /usr/share/doc/python3.12/README.venv for more information.

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.

I did as it suggested:

To install Python packages system-wide, try apt install python3-xyz, where xyz is the package you are trying to install.

so this has worked:

sudo apt install python3-virtualenv
sudo apt install python3-virtualenvwrapper

Answer 9

When running in a Docker container, use

RUN echo "[global]\nbreak-system-packages = true\n\n" > /etc/pip.conf

It fixes this bug by using the global pip configuration. VM and other junk is pointless in Docker containers and the obsession with Python virtual environments and "breaking packages" warning is likely from the "Java/Maven experience" that has serious version issues. Write your Python code to be 10 years backwards compatible instead, and skip all the VM nonsense. Only rarely do new libraries of good quality cause issues for old code, and when it does happen the issues can be patched.

Answer 10

Try these to avoid an externally managed env:

1. python3 -m venv path/to/venv.
2. source path/to/venv/bin/activate
3. python3 -m pip install xyz(any extension)

Answer 11

Working with a virtual environment.

Create a virtual environment:

python3 -m venv ~/myVirtualEnv

Access the virtual environment directory:

cd ~/myVirtualEnv

Activate (start) this virtual environment:

source bin/activate

Your shell changes to something like:

(myVirtualEnv) jose@nigriventer:~/myVirtualEnv$

If you are into myVirtualEnv, you can run pip3 directly to install packages. Of course, these packages will stay "locked" into this virtual environment:

pip3 install adafruit-ampy

Answer 12

I searched among the answers, and nobody tried the following approach.

I had the same error in my Spyder in Ubuntu 24.04 (Noble Numbat). However, I've noticed that if I run Python in the terminal, I can import the installed packages.

I've changed the Python interpreter in Spyder from "Tools" → "Preferences" → "Python interpreter" setting the address to /usr/bin/python3 that I can find from the terminal with the command which python3

After restarting, Spyder asks to install spyder-kernels==3.0.*, so I run from terminal

python3 -m pip install --break-system-packages spyder-kernels==3.0.*

Now it works.

Answer 13

If you use Conda, a simple conda install pip solves the issue.

Answer 14

The proper way to install Python libraries and applications is to install them in a Python virtual environment whenever possible (the exceptions to this rule are quite rare).

The error message describes two common ways to accomplish this: either by creating a virtual environment yourself, or for applications, by using pipx—a tool which will create a virtual environment for you and install the application in that virtual environment.

pipx is strongly recommended for installing applications, i.e., when you will primarily use the installed code from the command line. On Debian systems and Debian-based systems such as Ubuntu, you can install pipx using apt, and then use pipx to install the application:

apt install pipx
pipx install some-python-application

For libraries, i.e., when you will use the code primarily by importing it in your own projects. Typically, you should create a virtual environment yourself. You can do this with venv from the standard library:

python -m venv my-venv
my-venv/bin/pip install some-python-library

See also this answer on a duplicate question for more details.

(Commonly, your own project may need several libraries. Make one virtual environment and install the libraries that your project needs side by side in that virtual environment.)

---

If you have considered your options carefully and are still sure that you want to install packages "system-wide" and risk breaking your system (for example, by overwriting libraries that were part of tools written in Python that came with your system), Pip needs to be given permission to do so.

There are a few ways to do this:

• For a single use of pip, add the --break-system-packages argument to the command.

• Add these lines to ~/.config/pip/pip.conf (this will enable every future run of Pip to break system packages:

  [global]
  break-system-packages = true
  

• Use Pip's config command to edit the above file (credit to The Matt from the comments):

  python3 -m pip config set global.break-system-packages true
  

Theoretically, removing or renaming the "marker" file (/usr/lib/python3.x/EXTERNALLY-MANAGED) would also disable the block, but this is a bad idea. The file was put there for a reason, and it's at least as easy to use the intended mechanisms instead.

Answer 15

In my case, when I was trying to install mkdocs-material this error happened and the solution to it was:

Linux/Mac:

python3 -m venv venv
source venv/bin/activate

In the venv session:

pip3 --version
pip --version

Output:

pip 21.2.3 from .../python3.10/site-packages/pip (python 3.10)
pip 21.2.3 from .../python3.10/site-packages/pip (python 3.10)

Windows:

python -m venv venv
venv\Scripts\activate.bat

In the venv session:

pip3 --version
pip --version

Output:

pip 21.2.3 from ...\lib\site-packages\pip (python 3.10)
pip 21.2.3 from ...\lib\site-packages\pip (python 3.10)

Please read: Using pip in a Python Virtual Environment

Answer 16

This a works-for-all—Windows, Linux, macOS, Android, and Raspberry Pi—solution (put this at the end of your pip command): --break-system-packages

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

Answer 17

Use:

1. Open Terminal

2. Run sudo nano /etc/pip.conf

3. Add following line:

   [global]
   break-system-packages = true
   

4. Ctrl + X then Y → press Enter (perform save in the nano editor)

Everything is updated now you can run pip install <package_name>.

Answer 18

I've got this error since Python 3.11+.

Consider relevant comments received in this post from Alok and JackLeEmmerdeur:
This deletion of file is not safe. This can lead to Broken Package Management, Conflicting Installations and Permission Issues

So, find below the updated answer that allowed me to resolve this issue without the risk of compromising the system:

sudo mv /usr/lib/python3.11/EXTERNALLY-MANAGED /usr/lib/python3.11/EXTERNALLY-MANAGED.old

Answer 19

I started getting this error inside a virtual environment when I tried to modify it after upgrading my OS (Ubuntu). In this case, the solution was to recreate the virtual environment.

(venv) $ deactivate
$ rm -r venv/
$ python3 -m venv venv
$ source venv/bin/activate
(venv) $ pip install -e .
(venv) $ pip install <the package I want>

Answer 20

Another option nobody mentioned is to install from source! No need for pip or virtual environments. Simply download source and python setup.py install. I find this the best and less tedious way, especially that I use many modules that aren't provided by apt. Also, this approach works nicely with Dockerfile.

Answer 21

The OP did not specify whether the error happens in a virtual environment or not. Most answers I've seen assume it doesn't. I'm providing an answer for when this error occurs in a virtual environment.

The most likely cause of this error in a virtual environment is that the venv folder has been renamed or moved. Surprisingly, this is not allowed. The reason is that all the bin scripts as well as pyvenv.cfg use absolute paths. The safe and recommended action is to re-create a new venv as a copy of the defunct one. However, it is possible to 'fix' a renamed/moved virtual environment, by correcting all the paths. Here is a one-liner using sed that worked for me

cd <your_new_virtual_environment>
sed -i s'/<OLDPATH>/<NEWPATH>/g' pyvenv.cfg bin/*

Remember to escape / as \/ etc.

Answer 22

If you are in a virtual environment (which is recommended), sudo pip install .... will cause the "externally managed"-error. As "sudo" means system-wide installation, this seems to be a logical consequence.

I ran into this problem a few hours ago, being used to "sudo" when working on a project years ago.

pip install ...

within a virtual environment is the right thing to do.

Hope this helps anybody who is as little experienced as I am.

Answer 23

I was trying to get Ansible setup on Debian/Ubuntu when this error popped up, and here's the simplified answer to the solution that worked for me:

# Install venv if you don't have already. 
# Folder here .venv for me, but can be anything you choose
python3 -m venv .venv

# Now, lets use that virtual environment to install Ansible (or any package of your choice)
.venv/bin/pip3 install ansible

# Let's activate the virtual environment
source .venv/bin/activate

# Quick test, and congratulations! You got Ansible now! :-)
ansible --version

Thanks for others' answers. Sorry, pipx didn't quite worked for me, and venv did, and must admit I may be biased towards venv as I use it often). Also didn't want to enable the --break-system-packages option.

My comment is just to share my experience, and to simplify a quick course of action.

Answer 24

Simply go with:

sudo apt install python3-django

Answer 25

Context: I am ultimately building a Node.js image with a C++ dependency (node-libcurl), but I need python3 installed in order for node-gyp to build that C++ dependency for multiple architectures. I wrote this answer because too many other answers are taking the easy route of disabling the warning, where you risk punting a problem down the road to bite you later.

My Dockerfile was working fine until a recent build of python3 where setuptools was no longer explicitly included in apk install. This Dockerfile was working last year, but had since started to break. It simply wouldn't build. The node-gyp package uses gyp in python3, and it simply wasn't there due to a missing setuptools package.

ARG NODE_TAG=20-alpine
ARG PLATFORM_ARCH=linux/amd64

FROM --platform=${PLATFORM_ARCH} node:${NODE_TAG} as devBuild

WORKDIR /home

# ------------------
# dev dependencies
# ------------------
# node-libcurl build from source (works on x64 / arm64 as of Oct 2023)
RUN apk add --update --no-cache libcurl python3 alpine-sdk curl-dev \
  && npm install node-libcurl --build-from-source \
  && rm -rf /var/cache/apk/*dil
# ----------------

COPY package.json ./
COPY yarn.lock ./
RUN yarn install

# ... and so on

Based on this SO answer, I could see that getting setuptools was the solution. So I tried python3 -m pip install setuptools:

# ------------------
# dev dependencies
# ------------------
# node-libcurl build from source (works on x64 / arm64 as of Oct 2023)
RUN apk add --update --no-cache libcurl python3 alpine-sdk curl-dev \
  && python3 -m pip install setuptools \
  && npm install node-libcurl --build-from-source \
  && rm -rf /var/cache/apk/*dil
# ----------------

But it wasn't working, and I was getting the above message about an "externally-managed-environment", which led me to here on SO.

This message was advising me to use apk to install setuptools, since python3 was controlled by that tooling. So I finally realized (thanks to hints from other answers here) that I should add py3-setuptools in the dev dependencies section:

# ------------------
# dev dependencies
# ------------------
# node-libcurl build from source (works on x64 / arm64 as of Oct 2023)
RUN apk add --update --no-cache libcurl python3 py3-setuptools alpine-sdk curl-dev \
  && npm install node-libcurl --build-from-source \
  && rm -rf /var/cache/apk/*dil
# ----------------

And now I'm able to build my Node-based Docker image for both x64 and arm architectures again!

Answer 26

Just

python3 -m venv ~/.local --system-site-packages

Be sure ~/.local/bin is in your $PATH

Then use

~/.local/bin/pip install ... # --user is implied ;)

You could probably just create your own ~/py directory and initialize everything from there as well. However, I think .local is already picked up by PATH and import directories.

Answer 27

Navigate to cd /usr/lib/python3.11 then

sudo rm EXTERNALLY-MANAGED

Answer 28

To fix that error, you can use a Python virtual environment. Here is how you can do that.

Install a Python virtual environment

Then you can move into a directory that you wish and create a virtual environment using virtualenv your_folder_name. While in the environment you have created, type source bin/activate.

Here is an easy way (video).

Then that is it.

Answer 29

Take a look at this. It fixes it without using venv in Bash:

1. Open Terminal on Mac, and make sure your shell is Bash

2. Type nano ~/.bash_profile

3. Use arrow keys to go to the bottom of bash_profile

4. Paste export PATH=".:/Library/Frameworks/Python.framework/Versions/3.12/bin:/usr/local/bin:${PATH}" onto the bottom of bash_profile

5. Type Control + X, press Y, and then Enter

6. Type source ~/.bash_profile

7. Enjoy!

Answer 30

If you're using venv and you still get this error, try

pip cache purge