Currently, some of the most upvoted answers are teaching you ways to ignore this problem. This is like telling you to take pain-killers 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 envirnoment (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 install 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
.
sudo
when installing into a venv~
folder.