Key takeaways:
- The safest fix for the externally-managed-environment error is to create a separate virtual environment for each of your projects
- Use apt, dnf, or another system package manager for Python packages that belong in your operating system.
- Use pipx for Python command-line applications that you want available from the terminal.
You are seeing the error: externally-managed-environment because pip is trying to install a package into a Python environment that your operating system manages. That restriction exists to prevent pip from changing system packages and causing dependency conflicts. Most of the time, the best fix is to install the package inside a virtual environment instead.
Keep reading to see why the error happens and how to fix it.
Error: Externally-Managed-Environment - what it is and why it happens
An externally managed environment is a Python installation that is being controlled by an operating system package manager or another external package manager, rather than pip.
Linux distributions, to be specific, ship with Python installed because some software and system tools that come with the operating system are written in Python or depend on Python libraries.
So your OS may already have Python and system packages installed. When pip tries to install a package into that Python environment, it checks for a file called EXTERNALLY-MANAGED and blocks the installation.
This is important because pip could otherwise change a package that software on your system depends on.
For example, Ubuntu's add-apt-repository command depends on Python and system-managed Python packages. If pip replaced one of those dependencies with an incompatible version, the command could stop working.
That is the kind of problem the externally-managed-environment is designed to prevent.
Best practices for managing Python environments
Best practices for managing Python environments come down to matching each Python package with the package manager that should control it.
If Ubuntu itself needs a Python package, the system package manager should manage it. If your own Python project needs a package, put it in a virtual environment.
Doing this helps you avoid two problems:
- An ownership conflict, which happens when two package managers think they are responsible for the same package
- A dependency conflict, which happens when two programs need incompatible versions of the same package
Here are a few more tips to keep your Python environments clean and separate:
- Use a separate virtual environment for each Python project. For instance, our guide on Python web scraping shows you how to create an environment and add the libraries your scraper needs.
- Activate the virtual environment before installing packages with pip.
- Use python -m pip when you want to make sure pip is tied to the interpreter you are using.
- Keep your project dependencies in a file such as requirements.txt or pyproject.toml.
- Use apt, dnf, or your Linux distribution's package manager for packages that belong to the operating system.
Keeping system packages separate from your project dependencies makes it easier to see which package manager controls each part of your Python setup. For projects that send a large number of requests, you can route those requests through Residential Proxies.
Rotating residential IPs can target specific locations and reduce the chance of one IP being throttled for sending too many requests.
How to fix the error: Externally-Managed-Environment in Python
The right fix depends on what you are trying to install and whether it belongs to your own Python project or the operating system.
Using virtual environments (recommended solution)
If the package is for your own Python project, create a virtual environment and install it there instead of changing the system Python environment.
Step 1: Open your terminal
On Ubuntu and many other Linux desktop environments, you can press Ctrl + Alt + T to open a terminal.
Step 2: Check that Python 3 is installed
Run:
python3 --version
If Python 3 is installed, your terminal should return a version number such as:
Python 3.12.3
You may see a different version number, which is fine as long as it starts with Python 3. If it is not, download Python and install it.
Step 3: Move to the project you are working on
Suppose your project is saved in a directory called python-project. Run:
cd python-project
This moves your terminal into that project directory.
Step 4: Create the virtual environment
Run:
python3 -m venv .venv
This is what happens when you run this command:
- python3 runs your Python 3 interpreter
- -m venv runs Python's venv module, which creates virtual environments
- .venv is the name of the directory where Python will create the new virtual environment.
Step 5: Activate the virtual environment
Run:
source .venv/bin/activate
Your current shell will now use the Python interpreter and pip associated with .venv for this terminal session.
At this point, you’ll see (.venv) appear at the beginning of your command prompt.
Step 6: Confirm that you are using the virtual environment
Run:
command -v python
If everything is working correctly, the terminal should show a path pointing into the virtual environment you just created, such as:
/home/you/python-project/.venv/bin/python
This confirms that your shell is now using the Python interpreter inside .venv rather than the system Python.
Step 7: Install the package you originally wanted
You should now be able to install the package that caused the externally-managed-environment error. For example:
python -m pip install requests
In the example above, Python will install the Requests library in the environment you just created. For more information on the best library to use, see our guide on HTTPX vs Requests vs AIOHTTP.
Either way, a virtual environment like this one keeps your project dependencies separate from your system packages. You can then easily modify the packages your project needs without affecting the Python installation managed by the operating system.
Using a system package manager (alternative solution)
If the package you want to use belongs to the operating system rather than your own Python project, you can install it using the system package manager. This keeps the package under the control of the operating system instead of pip.
On Ubuntu or Debian, you use apt. On Fedora, you use dnf.
For this example, we will use python3-apt. This package provides Python access to the APT package management libraries used by Ubuntu and Debian. Because it belongs to the system package management setup, it should be installed and managed with apt.
Here is how to do that:
Step 1: Open the terminal
Press Ctrl + Alt + T to open your terminal.
Step 2: Check whether the package is available
Run:
apt show python3-apt
This lets you confirm that python3-apt is available through the package repositories configured on your computer.
Step 3: Update APT's package list
Run this command:
sudo apt update
to refresh APT's information about the packages available from your configured repositories.
Step 4: Install python3-apt
Run:
sudo apt install python3-apt
APT will tell you what it plans to install or change and may ask you to confirm. If python3-apt is already installed, APT will tell you that instead.
Step 5: Confirm that the package is working
Run:
python3 -c "import apt; print(apt.__file__)"
If everything worked, Python should show you the location of the installed apt module. If you see an import error instead, the package is not available to the system Python interpreter.
Using pipx to install applications
pipx is a utility for installing Python command-line applications in isolated environments. It automatically creates a virtual environment for each app it installs.
Suppose you want to install a Python application such as HTTPie and use it directly from your terminal. pipx comes in handy because it creates a virtual environment just for HTTPie and keeps its dependencies separate from the system Python.
The application is not tied to any one project, so you can run it from anywhere in your terminal.
Follow the steps below to install pipx on your Ubuntu pc:
Step 1: Open the terminal
Press Ctrl + Alt + T to open the terminal.
Step 2: Update APT's package list
Then enter this command:
sudo apt update
It will refresh Ubuntu's list of available packages from your configured repositories.
Step 3: Install pipx
Run:
sudo apt install pipx
This installs pipx using your system package manager.
Step 4: Add pipx applications to your PATH
Run:
pipx ensurepath
This ensures that the directory where pipx makes installed applications available is included in your PATH.
Step 5: Confirm that pipx is installed
Run:
pipx --version
If you see a version number, pipx is installed and working.
Step 6: Install a Python command-line application
You can now install a command-line application such as HTTPie with:
pipx install httpie
Once it is installed, you can run the http command from your terminal without activating its virtual environment first. And if you want to confirm the applications that pipx is managing, just run:
pipx list
Why proper Python environment management matters
A lot can go wrong when you put Python packages in the wrong environment or let unrelated software share the same Python environment. Here are a few potential consequences:
A pip install can break a system tool
Suppose Ubuntu has:
System Python
└── Package A 1.4,
and one of Ubuntu's tools depends on that package. You then run pip against the system Python and replace it with Package A 2.0.
At that point, the system tool could stop working because it encounters a version it was not packaged to use. This is why packages that belong to your own project are better kept inside a virtual environment rather than installed into the system Python.
and one of Ubuntu's tools depends on that package. You then run pip against the system Python and replace it with Package A 2.0.
At that point, the system tool could stop working because it encounters a version it was not packaged to use. This is why packages that belong to your own project are better kept inside a virtual environment rather than installed into the system Python.
One Python project can break another
Now suppose you have two Python projects. One uses Django 4.2, while the other needs Django 5.2. If both projects use the same Python environment, installing Django 5.2 for the second project can replace the version the first project depends on.
The safer approach is to give each project its own virtual environment. That way, one project can use Django 4.2 without being affected by the version installed for another project.
You can see this approach in practice in our Python Google Trends scraper, where we install the project's libraries inside a virtual environment before we build the scraper.
Your project could work on one machine and fail on another
If you keep installing your project's packages globally, the project may work on your computer simply because those packages are already there. Move the same project to another machine, and it may fail because that machine does not have the same packages installed.
Creating a virtual environment for each project helps avoid this. You should also record the project's dependencies in a file such as requirements.txt or pyproject.toml so the same environment can install the required packages when setting up the project on another machine.
Keeping each part of your Python setup in the environment meant for it reduces the chance that a package change in one place will break software somewhere else. If you're still experiencing errors, our guide to resolving parse errors in Python explains common syntax problems and how to fix them.
Conclusion
So there you have it. The reason your terminal showed the error: externally-managed-environment is that pip tried to install or modify a Python environment controlled by an operating system package manager. The restriction helps prevent dependency conflicts and stops pip from changing system packages that belong to another package manager.
For your own Python projects, use a separate virtual environment. If you are installing a command-line application, pipx can keep it isolated from the system Python. Join our Discord channel for more tips on Python errors and fixes.
