Fix the ‘externally-managed-environment’ Error on Raspberry Pi

Many older Raspberry Pi tutorials still show a simple pip install command to add Python packages. It worked for years, but on recent operating systems, it can now fail with an “externally-managed-environment” error. If this is the first time you’ve seen it, here’s what changed and how to fix it.

The externally-managed-environment error appears when pip tries to install packages into the system environment. It does this to avoid conflicts between packages managed by APT and packages installed manually.

In this guide, we’ll quickly explain why this happens, how to fix it properly, and which solution you should choose depending on your project. The goal isn’t to turn this into a full Python course, but to help you get unstuck without breaking your Raspberry Pi setup.

If you’re like me and sometimes mix up syntax between programming languages, I’ve got just the thing for you. I’ve put together a Python cheat sheet with all the essential syntax in one place, so you can keep it handy and avoid any confusion. Download it here for free!

Why the Externally Managed Environment Error Happens

This error usually appears on newer Raspberry Pi models with Debian 12 (or newer versions). It happens when you try to install a Python package globally with pip, outside of a virtual environment.

For example, if you run “pip install” requests directly on the system, Python may stop the installation and show the “externally-managed-environment” message.

Why? Well, the reason is simple: your system Python is now managed by the OS package manager, usually APT. This means your Raspberry Pi OS wants Python packages installed through the official repositories instead of pip.

This helps to prevent conflicts between packages installed by APT and packages installed manually!

Older tutorials often don’t mention this because it is relatively new. A few years ago, many guides simply told users to run pip install package-name, and it worked without warning. On newer systems, that same command now fails because Python follows stricter packaging rules:
python3 -m pip install requests

This can be annoying because the error shows up even when you are following a tutorial exactly. Nothing is really broken, but it feels like Python suddenly changed the rules. The important thing is to choose the right installation method instead of forcing the command immediately.

If you’re still getting comfortable with Python on Raspberry Pi, it’s worth starting with a basic Python tutorial for Raspberry Pi before going too deep into package management. Understanding how Python runs on the system makes errors like this much easier to diagnose later.

Solution 1: Install the Package with APT

If your Python project needs a common library, the most straightforward solution is to install it with APT. This makes the packages available to the entire system while keeping everything managed by Raspberry Pi OS.

This works because many popular Python libraries are already available as system packages. Instead of installing requests with pip, for example, if you install python3-requests with APT, the package is updated and maintained like the rest of your system software.

So, before using pip, it’s always worth checking whether the package exists in the official repo:
sudo apt update
sudo apt install python3-package-name

You can use this method when the package is available with apt, when you want a system-wide installation, or when the package is needed by a service running on the Raspberry Pi. It’s also a good choice for common packages like Flask, NumPy, Requests, or any library like this.

Choose APT if…

• The package is available in the Raspberry Pi OS repositories (aka Debian).
• You want the package installed system-wide.
• The package is needed by a service running on the Raspberry Pi.

But this doesn’t mean you should stop using pip completely. It just means you need to use it in the right place. If you want a clearer explanation of what pip does and how it works, I have a full guide about the pip command on Linux that explains the basics in more detail.

Tip: Command lines can be a pain to memorize. I put the essential Linux commands on a printable cheat sheet so you don't have to keep googling them. You can grab the PDF here if you want to save some time.

Solution 2: Use a Virtual Environment

When you’re developing a Python project, the best solution is usually to create a virtual environment. This gives your project its own isolated Python space instead of installing Python packages globally in your system.

This is a normal way to manage dependencies for scripts, web apps, bots, automation projects, and anything needing several Python packages. Your project gets the libraries it needs, and the rest of your Raspberry Pi stays untouched.

It also keeps you set up cleaner. One project can use one version of a package, while another project can use a different version. If something breaks, it only affects that project, not your entire Raspberry Pi.

To create and use a virtual environment, run:
sudo apt install python3-venv
mkdir my_project
cd my_project
python3 -m venv .venv
source .venv/bin/activate
pip install requests

Once the environment is activated, pip install works normally because the package is installed inside .venv, not into the protected system Python. You’ll usually know it’s active because your terminal prompt will show the environment name.

Choose a virtual environment if…

• You may have several Python projects on the same Raspberry Pi.
• You are working on a Python project or script.
• A tutorial asks you to install packages with:pip
• Your project needs several Python dependencies.
• You want to avoid conflicts with system packages.

For most Raspberry Pi projects, this is the method I recommend learning properly. I only covered the basic commands here, but you can follow this complete guide to Python virtual environments on Raspberry Pi for a detailed walk-through with examples.

Solution 3: Use pipx for Python Applications

pipx differs from a virtual environment because it’s not meant for project libraries. Instead, pipx is designed for installing Python command-line applications that run from your terminal.

The main difference is this: you use a virtual environment when your code needs to import a library, but you use pipx when you want to install a Python-based tool as a command. For example, tools like yt-dlp, black, or similar command-line apps are good options for pipx.

The advantage is that pipx automatically creates a separate environment for each application. You don’t have to create and activate a virtual environment manually, but the app stays isolated from the system Python installation.

For example:
sudo apt install pipx
pipx ensurepath
pipx install yt-dlp

After installing a tool with pipx, you can run it like a normal terminal command, but its dependencies stay separate from the rest of the system.

Choose pipx if…

• You are installing a Python command-line tool.
• You want the command available globally in the terminal like any other app.
• You don’t need to import the package inside your own Python code.
• You want isolation without manually managing a virtual environment.

This is why pipx deserves its own section. It is not a replacement for pip in every situation, and it is not just another way to install project dependencies. It solves a different problem: installing Python applications safely without affecting your system Python environment.

Solution 4: Force pip with –break-system-packages

This last solution is for cases where you intentionally want to install a package into the system Python environment anyway. It exists because some users, scripts, or older tutorials still expect pip to behave the old way.

You can force pip install into the system environment with:
python3 -m pip install package-name --break-system-packages

This bypasses the protection that caused the error in the first place. It may work in the moment, but it can also create the conflicts that the warning is telling you to avoid between the package manager (APT) and the packages installed by pip. In the worst case, some system tools that depend on Python Packages may stop working properly.

Choose –break-system-packages only if…

• You can afford to reinstall or repair the system if something breaks.
• You understand the risk.
• You are using a disposable test system.
• You have no better option.
• You are following a trusted guide that clearly explains why it is needed.

For beginners, I would avoid this solution unless a trusted guide specifically explains why it is needed. In most cases, apt, a virtual environment, or pipx will solve the problem more safely.

Best Practices to Avoid This Error

Once you understand why the “externally-managed-environment” error shows up, the most important thing is choosing the right installation method. The error doesn’t mean Python is broken on your Raspberry Pi. It simply means the system is protecting its own Python environment from accidental changes.

Here’s a quick decision guide that I recommend:

• Use APT if the package is available in the Raspberry Pi OS repositories.
• Use a virtual environment for most Python projects and tutorials.
• Use pipx for Python command-line applications.
• Use –break-system-packages only as a last resort.

The best habit is to avoid installing everything globally with pip. Using pip might feel faster at first, but it can quickly create conflicts, especially if you have several Python projects or apps running on the same Raspberry Pi.

For most projects, I recommend creating a separate folder and virtual environment. This keeps each project isolated and makes it easier to know which packages belong to which script. One project can use one set of dependencies, while another project uses a different set.

For bigger projects, it’s useful to save your dependencies in a requirements.txt file:
pip freeze > requirements.txt

Then, if you move the project to another Raspberry Pi or rebuild the environment later, you can reinstall everything with:
pip install -r requirements.txt

This becomes even more useful if you write code on another computer rather than directly on the Raspberry Pi. In that case, setting up remote Python development on Raspberry Pi can make it easier to manage projects, edit files, and keep each environment organized.

This error is more of a warning than a real problem. So, remember, for common packages use APT. For real Python projects, use a virtual environment. For Python CLI tools, use pipx. And only force pip with –break-system-packages when you fully understand the risk.

Not getting the same result?

Even when you follow every step, small differences in OS version, hardware or config can change the outcome. Instead of wasting time guessing, get help from people who have already fixed the same kind of issue.

Ask your question now →

🔒 No risk. Cancel anytime.

• Get help on your exact issue
• Access step-by-step videos for tricky setups
• Browse the website without ads