pip: error: externally-managed-environment on Linux and Raspberry Pi

Make a virtual environment and install the package inside it. Do not force the install into the system Python.

What the message means

Newer operating systems protect the system Python so that pip cannot break the tools that depend on it.

Fix it in this order

Create an environment with python3 -m venv name.
Activate it and run pip install there.
Use --system-site-packages when the environment needs the system camera or GPIO libraries.
Install a ready-made system package with apt where one exists.
Use pipx for command-line tools.
Avoid the break-system-packages option unless you accept the risk.

Why it happens

Some operating systems let their own tools depend on the system Python and its packages. If pip installed or upgraded packages there, it could replace a version those tools need and break them. The error is the system saying the Python is managed by the package manager and pip should stay out of it.

A virtual environment is a separate folder with its own packages, so installing there cannot touch the system copy. Forcing the install past the warning removes that protection, which is why it is the last thing to try.

If you see this, do this

You see	Do this
Error on pip install	Use a virtual environment.
Module missing inside the environment	Install it there or add system site packages.

No module named cv2, serial permission denied.

Last reviewed: November 2026. These are the usual causes and the order that finds them fastest. Test on your own board; clones and cables differ.

Why this happens

Some systems, including recent Debian-based releases such as Raspberry Pi OS, use the system Python for their own tools. If pip installed or upgraded packages there, a version those tools rely on could be replaced and break the system. The distribution marks its Python as externally managed with a marker file, and pip refuses to continue when it sees it.

A virtual environment is a separate folder with its own copy of the packages. Installing there cannot touch the system copy, and deleting the folder removes everything. This is why the standard answer is a virtual environment, not a forced install.

How to confirm the cause

Read the whole error text. It names the problem and suggests the safe options.
Run python3 –version to see which Python you are using.
Check whether you are already inside a virtual environment: python3 -c “import sys; print(sys.prefix != sys.base_prefix)”. True means yes.
Look for the marker file in the standard library folder of the interpreter. Find the folder with python3 -c “import sysconfig; print(sysconfig.get_path(‘stdlib’))”.
Check whether the library you want is available as a system package, which you install with apt.

Worked example

Create an environment, install a package and check it. The first command lets the environment see system packages such as the camera library.

python3 -m venv --system-site-packages ~/robot-env
source ~/robot-env/bin/activate
python -m pip install opencv-python
python -c "import cv2; print(cv2.__version__)"
deactivate
# later runs: ~/robot-env/bin/python myscript.py

Common mistakes

Using sudo pip.
Reaching for the break-system-packages option first.
Deleting the marker file.
Making the environment but starting scripts with the system Python, for example from a service or scheduled job.
Forgetting to activate the environment in a new terminal.

If this did not fix it

The venv module is missing. Install the python3-venv package with apt.
The system package has a different name from the pip name, so search apt for it.
The editor is set to the wrong interpreter, so imports fail inside it only.