51

I upgraded to Ubuntu 23.04. Now, when I run a pip command (installed using sudo apt install python3-pip), I get this error:

$ pip install --user <foobar>
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 mean? How can I avoid this error?

What if I want to install a package user-wide (--user), not system-wide? How do I do that?

Flimm
  • 43,943

6 Answers6

49

There's a good article on OMGUbuntu about this: 3 Ways to Solve Pip Install Error on Ubuntu 23.04

Here's the summary. There are three ways to approach this problem:

1. Install the Python package using APT

For instance, if you want to install the requests Python library, you can install it using APT instead, like this:

sudo apt install python3-requests

This will install this library system-wide.

Not all packages available on PyPI have been packaged and included in the Debian/Ubuntu repositories, so this method won't work for some packages.

Or: 2. Create a virtual environment using venv or virtualenv

Make sure venv is installed by running:

sudo apt install python3-venv

To create a new virtual environment in a directory named .venv, run:

python3 -m venv .venv

To activate this virtual environment (which modifies the PATH environment variable), run this:

source .venv/bin/activate

Now you can install a library like requests in this virtual environment:

pip install requests

The files will get installed under the .venv/ directory.

If you want to leave the virtual environment, you can run:

deactivate

If you don't want to run source .venv/bin/activate and deactivate, then you can run the executable by prefixing its path, like this:

 $ .venv/bin/pip install requests
 $ .venv/bin/python3
 >>> import request
 >>> help(requests)

Or: 3. Use pipx

pipx lets you install and run Python applications in isolated environments. This is the recommended way to install PyPI packages that represent command-line applications.

To install pipx, run:

 sudo apt install pipx

pipx needs ~/.local/bin/ to be in your PATH. You can automatically modify your shell configuration (such as ~/.bashrc) to modify PATH appropriately by running:

 pipx ensurepath

(You may need to close your terminal application and open it again for the changes to take effect.)

Now you can install a package from PyPI, like this:

 pipx install pycowsay

And you can run the command that you just installed, like this:

$ pycowsay Mooo!




< Mooo! >


\   ^^
\  (oo)_______
()\       )/

||----w |
||     ||

As you can see, pipx installed a symlink in ~/.local/bin/ to the executable in a virtual environment:

$ ls -l ~/.local/bin/pycowsay
lrwxrwxrwx 1 flimm flimm 50 May 24 11:19 /home/flimm/.local/bin/pycowsay -> /home/flimm/.local/pipx/venvs/pycowsay/bin/pycowsay*

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

If you want to ignore the warning, you can pass the --break-system-packages flag:

pip install --break-system-packages --user <foobar>

This method is not recommended, because you may find yourself with mysterious broken installations of Python packages months or years later, after you've forgotten that you used --break-system-packages and installed other conflicting Python packages.

Flimm
  • 43,943
  • 1
    After using the virtual environment, I still get the error message about the externally managed environment. Even though I can confirm I am using the virtual env and it's installing into there if I use the --break-system-packages flag. Do you have any idea why this might be? This was inside a Docker container. – Nick Jun 23 '23 at 14:21
  • 1
    I actually really appreciate this answer (probably why I've bricked Ubuntu in the past)... I'd add you could also use "brew install" on Linux too – Ben Winding Mar 07 '24 at 12:57
  • 1
    I used pipx as described. Did what it said on the tin. Thank you. – Captain Normal Mar 22 '24 at 11:25
  • When installing a package with --user, how would it break anything? I think --user should always be allowed, regardless of whether the system environment is externally managed – Derkades Nov 27 '24 at 20:41
  • 2
    @Derkades It could break any Python program running as that user (as opposed to running as another user on your system). For example, if the text editor gedit loads a Python plugin that expects certain Python dependencies to exist in certain version, and not other depencies, installing something using pip install --user could break the gedit plugin. gedit runs as your user, so it is affected by Python dependencies installed under ~/.local/lib/python3.11/ or similar – Flimm Nov 28 '24 at 08:13
  • Installing packages in my private "site-packages" folder cannot break the "system", it can only break my system. And the performance penalties of a virtual environment are not acceptable!! – John Anderson May 25 '25 at 13:12
  • 1
    @JohnAnderson um... what performance penalties? A virtual environment isn't like a VM where you do have penalties, it's just a specially configured Python executable process that is configured with a different site packages root... thus not breaking anything in your system Python. – Thomas Ward Jul 17 '25 at 17:00
11

In a terminal, delete this file with:

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

and everything will be OK!

TommyPeanuts
  • 1,157
amir hosein
  • 121
  • 3
    Unfortunately, I have to downvote this answer. Everything will not be OK if someone does this. It will cause problems later on, when you install libraries and applications from the repositories that rely on system Python, when they are conflicts with things installed with Pip. If you really need a Python that is not externally managed, you can compile it yourself or use a tool like pyenv – Flimm Apr 23 '24 at 09:54
  • This answer has over 200 votes, #2 accepted answer at https://stackoverflow.com/questions/75608323/how-do-i-solve-error-externally-managed-environment-every-time-i-use-pip-3. This is really a duplicate question (and answer). – rtaft Apr 25 '24 at 14:55
3

Had the same error on my Ubuntu 23.04. I tried pip install {package_name} --break-system-packages It worked for me. Hope it helps. Thank you.

Clarion Isige
  • 31
  • 3
    Please, for your own sanity, do not do this and just read the error message instead. The break-system-packages should give you all the hint why you shouldn't do that... – Izzy Aug 03 '23 at 21:27
2

A quick solution to this problem is directly using the python inside the env.

1.- Create the virtual environment: python -m venv <env_name>

2.- Activated it: source <env_name>/bin/activate

3.- Install the package you need: sudo venv/bin/python3 -m pip install <package_name>

This should fix it.

Roige A.
  • 21
  • 1
0

If you've got the venv set up and are still getting the error, make sure the venv folder has the correct permissions. I spent a long time spinning my wheels before I chown'd the folder to my username. Then do not use sudo.

Check folder owner:

  1. Go to the parent folder

  2. List the folder's owner with:

     ls -Al

  3. If the folder is owned by root in group root:

     chown -R username:username ./venvfolder/
Beowulf
  • 1
  • Thanks Beowulf! That's helpful to know. My guess is that this problem would have been caused by running sudo python3 -m venv venvfolder with sudo. To avoid this problem, run the command without sudo . – Flimm Sep 27 '23 at 09:34
  • I didn't upvote because this technically isn't an answer to the question post, but I want to thank you for your contribution. – Flimm Sep 27 '23 at 09:38
  • Yeah I wanted to comment, but it wouldn't let me because I didn't have enough reputation? Not sure why. – Beowulf Sep 29 '23 at 22:42
-1

I had created the conda virtual environment, and facing the same issue with pip , so conda install kafka-python worked for me

Raj
  • 1
  • 1