externally-managed-environment 오류 해결 4가지

우분투나 라즈베리파이를 새로 밀고 나서 pip install requests 한 줄을 쳤는데, 설치는커녕 빨간 글씨로 error: externally-managed-environment가 뜹니다. 어제까지 쓰던 명령어인데 갑자기 막히니까 pip이 깨진 건가 싶어 재설치까지 해보게 되죠. 결론부터 말하면 pip은 멀쩡합니다. 리눅스 배포판이 "시스템 파이썬은 건드리지 마라"고 선을 그은 것뿐이고, 해결법은 상황별로 네 가지입니다.

3줄 핵심 요약

1. 이 오류는 PEP 668 정책 때문이며, 데비안 12·우분투 23.04 이상·라즈베리파이 OS 북웜부터 기본 적용됩니다.
2. 정석 해결은 가상환경(venv), CLI 도구 설치라면 pipx, 시스템 전역이 꼭 필요하면 apt입니다.
3. --break-system-packages는 임시방편이고, EXTERNALLY-MANAGED 파일 삭제는 절대 하면 안 됩니다.

1. 왜 갑자기 막혔나 — PEP 668이 하는 일

원인은 소유권 충돌입니다. apt는 파이썬 패키지들을 하나의 세트로 묶어 버전을 맞춰 관리하는데, pip은 그 사정을 전혀 모르고 같은 디렉터리에 파일을 덮어씁니다. 그 결과 apt가 설치한 시스템 스크립트가 조용히 망가지는 사고가 반복됐습니다. 그래서 PEP 668은 시스템 파이썬 폴더에 EXTERNALLY-MANAGED라는 표식 파일을 두고, pip이 그 파일을 보면 전역 설치를 거부하도록 정했습니다.

즉 오류가 아니라 의도된 차단입니다. 내 PC만의 문제가 아니라는 뜻이기도 합니다.

환경	적용 시작 버전	비고
데비안	12 (bookworm)	최초 적용
우분투	23.04 이상 (24.04 LTS 포함)	LTS 사용자도 해당
라즈베리파이 OS	Bookworm	국내 문의가 가장 많은 구간
페도라	38 이상	-
macOS Homebrew	Python 3.11 이후 포뮬러	맥에서도 동일 메시지

2. 해결책 4가지 한눈에 비교

방법	적합한 상황	시스템 안전성	난이도
venv 가상환경	프로젝트 개발·학습	매우 안전	쉬움
pipx	터미널에서 명령어로 쓰는 도구 설치	매우 안전	쉬움
apt로 설치	시스템 전역에 꼭 있어야 할 라이브러리	안전	쉬움
--break-system-packages	일회성 테스트, 폐기 예정 장비	위험	매우 쉬움

3. 방법별 실제 명령어

① venv — 가장 많이 쓰게 될 정석

sudo apt install python3-venv -y
python3 -m venv ~/myenv
source ~/myenv/bin/activate
pip install requests

프롬프트 앞에 (myenv)가 붙으면 성공입니다. 빠져나올 때는 deactivate를 칩니다. 참고로 파이썬 requests 설치와 크롤링 예제에서 쓴 sudo pip install 방식은 이제 이 가상환경 안에서 sudo 없이 쓰는 형태로 바꿔 주시면 됩니다.

② pipx — 도구를 명령어처럼 쓸 때

sudo apt install pipx -y
pipx ensurepath
pipx install black

pipx는 도구마다 격리된 가상환경을 자동으로 만들고 실행 파일만 ~/.local/bin에 연결합니다. black, yt-dlp처럼 터미널에서 명령어로 치는 패키지는 전부 이쪽이 맞습니다.

③ apt — 시스템 전역이 필요할 때

sudo apt install python3-numpy python3-matplotlib

패키지 이름 앞에 python3-를 붙이는 규칙입니다. 다만 배포판이 검증한 버전이라 최신판보다 한두 단계 낮을 수 있습니다. GUI 백엔드가 없어 생기는 No module named _tkinter 오류처럼, 시스템 라이브러리와 엮인 문제는 오히려 apt 쪽이 깔끔하게 풀립니다.

④ --break-system-packages — 마지막 수단

pip install requests --break-system-packages

옵션 이름 그대로 "시스템 패키지를 깨뜨려도 좋다"는 선언입니다. 도커 컨테이너나 곧 초기화할 실습용 라즈베리파이처럼 망가져도 상관없는 환경에서만 쓰세요.

4. 절대 하지 말아야 할 것

검색하다 보면 EXTERNALLY-MANAGED 파일을 지우라는 글이 꽤 나옵니다. 실제로 오류는 사라집니다. 그런데 그 뒤가 문제입니다.

• apt가 관리하던 패키지를 pip이 덮어써 시스템 도구가 실행되지 않습니다 (우분투에서는 apt 자체가 파이썬에 의존합니다)
• 배포판 업그레이드 시 의존성 충돌로 업그레이드가 중단됩니다
• 문제가 터졌을 때 원인 추적이 사실상 불가능합니다

같은 이유로 sudo pip install도 이제는 피해야 할 습관입니다.

5. 상황별 선택 가이드

지금 하려는 일	선택
파이썬 공부·토이 프로젝트	venv
여러 프로젝트를 오가며 개발	venv (프로젝트별로 하나씩)
black, yt-dlp 같은 CLI 도구 설치	pipx
서버 스크립트를 cron으로 돌림	venv + 절대경로 실행
도커 이미지 빌드	--break-system-packages 허용

실전 팁 & 체크포인트

• venv 폴더는 프로젝트 안에 두고 .gitignore에 추가하세요. 관례상 이름은 .venv입니다.
• pip freeze > requirements.txt로 목록을 남겨두면 환경을 언제든 다시 만들 수 있습니다.
• cron이나 systemd에서 실행할 때는 source 대신 ~/myenv/bin/python script.py처럼 가상환경의 파이썬 경로를 직접 지정하는 편이 안정적입니다.
• 가상환경 만들기 자체가 실패한다면 python3-venv 패키지가 안 깔린 경우가 대부분입니다.

자주 묻는 질문

Q. sudo를 붙이면 되지 않나요?
안 됩니다. 권한 문제가 아니라 정책 차단이라 sudo pip install도 동일한 메시지가 뜹니다.

Q. 가상환경을 만들면 기존에 깔아둔 패키지는 못 쓰나요?
기본값으로는 격리됩니다. 시스템 패키지를 같이 보고 싶다면 python3 -m venv --system-site-packages ~/myenv로 만드세요.

Q. 윈도우에서도 이 오류가 나나요?
윈도우 공식 설치본에는 이 표식 파일이 없어 발생하지 않습니다. 단, WSL 안의 우분투는 리눅스와 동일하게 적용됩니다.

마무리

정리하면 이렇습니다. 개발은 venv, 도구 설치는 pipx, 시스템 전역은 apt, 그리고 --break-system-packages는 버려도 되는 환경에서만. 이 네 줄만 기억하면 배포판을 새로 밀 때마다 같은 검색을 반복할 일은 없습니다.

참고 자료

• PEP 668 – Marking Python base environments as "externally managed" (python.org)
• Externally managed environments: when PEP 668 breaks pip (pythonspeed.com)
• Fix the externally-managed-environment Error on Raspberry Pi (raspberrytips.com)