by In this quick guide, we will show you how to solve the Externally Managed Environment error when attempting to install Python packages using pip.
Recent versions of operating systems, such as Raspberry Pi OS Bookwork, Debian 12, and Ubuntu 24, have made changes that make installing Python packages using the Pip package manager more difficult.
These operating systems have begun to adopt PEP 668. This proposal allowed operating systems to prevent the installation of Python packages in the global operating system. Packages installed through pip can sometimes break those installed by the operating system. With this proposal, Python libraries installed through pip are expected to be installed within a Python virtual environment.
These Python environments allow you to install and set up packages without affecting the rest of your system. The downside is that they can be quite clunky to work with if you aren’t too familiar with Python or if you are just trying to run a script quickly.
If you attempt to install a Python package using pip outside a virtual environment, you will run into an error stating that you have an “externally managed environment“. Below you can see an example of how this error can appear on your system.
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.
For more information visit http://rptl.io/venv
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.The best alternative is to install the Python package directly from your operating system repository. For example, you can install the requests package on Ubuntu by running “sudo apt install python3-requests“.
However, if the Python library isn’t available through the official package manager, you can use a few workarounds to avoid the “externally-managed-environment” error when using pip.
In the following sections, we will show you how to temporarily or permanently fix this error.
Temporarily Overriding the Externally Managed Environment Error
While the easiest workaround for the externally managed environment error is to install the package directly from your operating system’s package repository, this isn’t always the best choice.
For starters, the Python library in a repository is typically older than that provided through Pip. Secondly, not all Python libraries can be found within an operating systems package repository.
Luckily, there are other workarounds. If you want to temporarily avoid this error, you can include the “--break-system-packages” option when installing libraries through pip. This option tells Python to install a library regardless of the managed environment.
You must use this option whenever you want to install a Python library through pip.
1. Below, we show you an example of using the “--break-system-packages” option to override the managed environment error.
With this example, we call Python directly and tell it to use the “pip” module.
python -m pip install requests --break-system-packages2. Alternatively, you can call Pip directly to install a Python library. Again, we are using the “--break-system-packages” option to avoid the “error: externally-managed-environment” error.
pip3 install requests --break-system-packagesHow to Permanently Suppress the “error: externally-managed-environment” Error when using Pip
It is also possible to permanently suppress the externally managed environment error when installing a library through pip by setting the “break-system-packages” option to “true” globally.
Setting this option is relatively easy, as the Pip package manager has a built-in tool for setting configuration options.
The only downside of this method is that it does not apply to each user. This is because pip checks for the config file within the user’s home directory.
1. By running the following command, you will set the “break-system-packages” option to true for your current user.
Each user has its own configuration file, so you will need to run this for each individual user that you use “pip” with.
This command generates a config file within your current user’s home directory; within this file, the “break-system-packages” option will be set to true. Next time you install a Python library, you will not encounter the “Externally Managed Environment” error.
python3 -m pip config set global.break-system-packages true2. As mentioned before, this option only applies to your current user. This means you must run the command for every user, including the root user.
For example, you can use the command below to suppress the “externally-managed-packages” error for your superuser.
sudo python3 -m pip config set global.break-system-packages trueConclusion
Hopefully, by this point in the guide, you will have a good idea of how to suppress the “externally managed environment” error on your system.
This error will become increasingly common as more operating systems adopt PEP 668 as part of their Python distribution.
Luckily, there are plenty of ways to avoid this error if you want to return to the older way of installing Python packages and remove your reliance on Python environment variables.
Please feel free to leave a comment below if you have any questions about dealing with this error.
If you liked this tutorial, we highly recommend checking out our many other Python, Linux, or Raspberry Pi tutorials.
