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

Raspberry Pi OS (Bookworm) 이후 버전부터 Debian 계열 기본 Python 환경이 PEP 668을 적용하여, 시스템 패키지 관리자가 관리하는 Python 환경에 외부 패키지를 직접 설치하지 못하도록 보호하고 있습니다.
pip install 명령 실행 시 아래와 같은 오류가 발생하는 이유입니다.


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.

라즈베리 파이처럼 개인 프로젝트나 단일 목적 장비에서는 매번 가상환경을 만드는 게 번거로울 수 있습니다.
아래 두 가지 방법 중 하나로 전역 설정을 변경하면 이 오류 없이 pip install을 사용할 수 있습니다.

Method 1: Delete EXTERNALLY-MANAGED file

이 방법은 보호 장치 파일 자체를 삭제하여 pip의 제한을 제거합니다.
먼저 파일 위치를 확인한 뒤 삭제합니다.


Find and delete EXTERNALLY-MANAGED
sh

삭제 후에는 별도의 옵션 없이 pip install이 정상 동작합니다.
단, Python 버전이 업그레이드될 경우 파일이 다시 생성될 수 있으므로 재확인이 필요합니다.

Method 2: Configure pip globally (Recommended)

이 방법은 pip 전역 설정에 break-system-packages = true를 추가하여, 파일을 삭제하지 않고도 항상 허용 상태로 유지합니다.


Set pip global config
sh

설정이 적용된 pip.conf 내용은 다음과 같습니다.


~/.config/pip/pip.conf
config

이후 pip install <package> 명령이 추가 옵션 없이 정상 동작합니다.

Summary

Method	장점	단점
EXTERNALLY-MANAGED 삭제	설정 없이 즉시 해결	Python 업그레이드 시 재삭제 필요
pip config 전역 설정	업그레이드 후에도 유지됨	pip.conf 위치가 실행 유저에 따라 다를 수 있음

개인 라즈베리 파이 환경이라면 Method 2 (pip config)가 더 지속적인 해결책입니다.

PreviousSetting Timezone to KST Using timedatectl

NextFixing OS File Watch Limit Reached Error