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.

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

The --break-system-packages flag in pip allows to override the externally-managed-environment error and install Python packages system-wide.

pip install package_name --break-system-packages

Note: Usage of this flag shouldn't be abused.

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.

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.

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

I installed pipx first:

apt install pipx

Then I used pipx to install radian:

pipx install radian

Later to confirm the installation location (in my case to configure Visual Studio Code), I ran:

pipx list

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>.

# rm /usr/lib/python3.11/EXTERNALLY-MANAGED

That issue is from pip. Just run the command and it will downgrade it.

pip install pip==22.3.1 --break-system-packages

Surely that will help.

Python is like hell for system administrators... Different software use different versions of many different things.

A few times, I've used pip3 to install things... that break other things. Sometimes I mix it with "apt-get install".

This error message is just like heaven... because it forces us to do the things right. It means the package manager (Ubuntu, Debian) is responsible for handling dependencies, not pip.

It's why we have Conda, or Miniconda.

You can create an environment using something like

conda create --name thenameofmyapp python=3.8

Activate your environment using

conda activate pixray

Then you can "pip install -r requirements.txt" and it will not break your system :) It will just install things in a specific environment.

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

Create .venv

python3 -m venv .venv

Then you have to use pip inside your .venv folder

.venv/bin/pip install -r requirements.txt

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

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

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

I was trying to get Ansible set up 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 it already. 
# The folder here is .venv for me, but it can be anything you choose
python3 -m venv .venv

# Now, let’s 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 I didn't want to enable the --break-system-packages option.

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.

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)

Do the following:

cd /usr/lib/python3.11

sudo rm EXTERNALLY-MANAGED

If you choose to restore this mechanism, create the same file again with the touch command:

sudo touch EXTERNALLY-MANAGED

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

For the case where you've requested the Python Feature as an add on to a Dev Container, it turns out that this problem can be solved simply by explicitly setting the Python version.

With the default "version", pip install fails:

"features": {
    "ghcr.io/devcontainers/features/python:1": {}
}

With an explicit "version", pip install succeeds:

"features": {
    "ghcr.io/devcontainers/features/python:1": {
        "version": "3.13"
    }
}

By making this change to ".devcontainer.json", you avoid the requirement of concerning yourself with the complexities of Python Virtual Environments inside your development containers.

Some explanation of why this works

The issue, in this case, is that the default value for "version" is "os-provided" which is natively incompatible with pip install as described in PEP 668. Overriding "version" will result in a separate "/usr/local" install of Python, which doesn't suffer from the problem. When interacting with the "local" version, pip install will manage packages in the "site-packages" folder along with the local install.

Note: The selection of which installed Python is used for your development work comes down to how Python is invoked inside of your container.

One other way to install packages that are not available via the distribution's package manager may be pip's prefix option, as documented at packaging.python.org

pip install --prefix=/some/path

Calls sysconfig.get_preferred_scheme('prefix').

The prefix is distribution dependent. E.g., Debian uses /usr/local for packages not installed via the system package manager.

Some gotchas are also possible. On Devuan (so possibly also on Debian itself and other derivatives), the prefix needed to target /usr/local is /usr:

pip install --prefix=/usr some_package

installs some_package in /usr/local where it is visible to applications installed by the system package manager.

However,

pip install --prefix=/usr/local some_package 

installs some_package in /usr/local/local, which does not work.

I ran across this problem while running some tasks on a pipeline job that uses the Docker image. I hadn't had this problem before, but since I am not using any specific tag for the Docker image, I am also not very surprised.

I was running the command:

python3 -m pip install --upgrade pip

which I replaced with:

python3 -m pip install --upgrade pip --break-system-packages

And things worked as usual.

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.

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>

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!

This is just a specific case, but it may be helpful for someone:

I had a virtual environment on Linux for Python 3 and pip and still got the message above.

The virtual environment was used and did work for Python 3, but not for pip.

The reason for this was that the directory for the virtual environment was named venv and not .venv.

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.

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