Fixing pip externally-managed-environment Error on Raspbian

How to globally fix the pip externally-managed-environment error on Raspberry Pi OS

May 10, 2026

Fixing pip externally-managed-environment Error on Raspbian

Starting from Raspberry Pi OS (Bookworm), the default Python environment in Debian-based systems enforces PEP 668, which prevents installing external packages directly into the Python environment managed by the system package manager.
This is why running pip install triggers the error below.


error: externally-managed-environment
Doc
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.

For personal projects or single-purpose devices like a Raspberry Pi, creating a virtual environment every time can be tedious.
You can change the global setting using one of the two methods below to use pip install without this error.

Method 1: Delete EXTERNALLY-MANAGED file

This method removes pip's restriction by deleting the guard file itself.
First, find the file location and then delete it.


Find and delete EXTERNALLY-MANAGED
sh

After deletion, pip install works normally without any additional options.
Note that if Python is upgraded, the file may be recreated, so you will need to check again.

Method 2: Configure pip globally (Recommended)

This method adds break-system-packages = true to the pip global config, keeping it always allowed without deleting the file.


Set pip global config
sh

The pip.conf content after applying the setting is as follows.


~/.config/pip/pip.conf
config

After this, pip install <package> works normally without any additional options.

Summary

Method	Pros	Cons
Delete EXTERNALLY-MANAGED	Immediate fix without configuration	Needs re-deletion after Python upgrade
pip config global setting	Persists after Python upgrade	pip.conf location may vary by user

For a personal Raspberry Pi environment, Method 2 (pip config) is the more persistent solution.

PreviousSetting Timezone to KST Using timedatectl

NextFixing OS File Watch Limit Reached Error