If you’ve tried to install a Python package using pip install recently, and you’re running Debian 12 (or a derivative like Parrot 6 in my case) you may have been stumped by this error message:
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’s going on here? Essentially, the externally-managed-environment error occurs when the system package manager (so apt, in this case) is managing Python packages, as a result, pip is not allowed (by default) to interfere with Python packages. If we take a look at the Python enhancement proposal PEP 668 we can see that the objective of this change is essentially to prevent users from unintentionally modifying packages which are required by the distribution and breaking stuff. Actually, this is a pretty good idea - however, it can be a pain if you’d rather run the risk and continue to use pip with reckless abandon like I would.
It’s worth pointing out that if you’re managing a production system, you really should follow the advice given and try to install your required package using apt to get the version which is supported in your Distro’s repository - simply run sudo apt install python3-[desired package]. Again, if you need a non-supported package using a venv is the best way to go
If, however, you want to be reckless, you have two options..
Option 1 - Break system packages
The error message says you can pass in the flag --break-system-packages and you can do exactly that - this won’t deliberately break system packages, rather it’s just overriding the protection which has been introduced and doing what pip always used to do. It might break some system packages though - it kinda told you that :)
If using a venv is more effort than you want to put in (pipx does make this quite easy!) a good halfway house would be to try getting the package from apt first, and then use --break-system-packages if the package isn’t present in the repo.
Option 2 - Delete EXTERNALLY-MANAGED
For a longer-term solution which will totally disable this message, you can delete the EXTERNALLY-MANAGED file in your system Python installation:
sudo rm -rf /usr/lib/python3.11/EXTERNALLY-MANAGED
This will totally disable the protection though, so use with care. Python 3.11 is current as I’m writing this but by the time you read it, that directory might be different based on the current version.