pip externally-managed-environment 에러 해결법 (PEP 668)

"어제까지 되던 pip install이 왜 갑자기 에러가 나죠?"

Ubuntu를 23.04 이상으로 올리거나, Debian 12(bookworm)로 갈아타거나, macOS에서 Homebrew Python을 3.12로 업데이트한 뒤 이런 화면을 만난 분들이 많습니다.

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.
    ...

note: If you believe this is a mistake, please contact your
Python installation or OS distribution provider.
hint: See PEP 668 for the detailed specification.

결론부터 말하면 이건 버그가 아니라 의도된 정책 변화입니다. 파이썬이 잘못 설치된 것도, 여러분이 명령어를 틀리게 친 것도 아닙니다. 배포판이 시스템 파이썬을 보호하기 위해 EXTERNALLY-MANAGED라는 마커 파일을 심어 두었고, pip가 그것을 감지해 시스템 전역 설치를 거부하고 있는 것뿐입니다.

이 글에서는 (1) 왜 막혔는지 30초 만에 이해하고, (2) 내 상황에 맞는 해법을 판정표로 고르고, (3) 복붙해서 바로 실행할 수 있는 명령어까지 한 번에 정리합니다. 그리고 시스템을 망가뜨리는 위험한 우회법이 왜 위험한지도 짚어드립니다.

왜 이 에러가 생겼나 — PEP 668 30초 요약

externally-managed-environment의 정체는 간단합니다. apt/dnf/brew 같은 OS 패키지 관리자가 관리하는 파이썬 환경에, pip가 마음대로 패키지를 끼워 넣지 못하게 막는 안전장치입니다.

과거에는 sudo pip install로 시스템 파이썬에 아무 패키지나 설치할 수 있었습니다. 문제는 apt가 설치한 python3-requests와 pip가 설치한 requests가 같은 디렉터리에서 충돌하면서, apt 자체나 시스템 유틸리티(예: apt, netplan, ubuntu-drivers)가 깨지는 사고가 반복됐다는 점입니다. 이를 막기 위해 PEP 668이 도입됐고, pip는 다음 위치의 마커 파일을 감지하면 설치를 거부합니다.

• Debian/Ubuntu: /usr/lib/python3.11/EXTERNALLY-MANAGED (버전에 따라 3.11/3.12 등)
• Homebrew: /opt/homebrew/lib/python3.12/EXTERNALLY-MANAGED (또는 /usr/local/...)

적용이 시작된 대표 버전은 다음과 같습니다.

즉, "명령이 갑자기 실패한" 이유는 여러분의 잘못이 아니라 OS가 규칙을 바꿨기 때문입니다. 규칙을 이해하면 해법도 명확해집니다.

30초 원인 판정표 — 내 상황엔 뭘 써야 하나

무작정 --break-system-packages부터 찾지 마세요. 지금 하려던 일이 아래 네 갈래 중 어디인지만 정하면 해법이 정해집니다.

이 표에서 자기 행을 찾았다면, 아래 해당 해법 섹션으로 바로 이동하면 됩니다.

해법별 정확한 명령어와 트레이드오프

(a) venv — 표준이자 가장 안전한 정답

특정 프로젝트에서 패키지를 쓴다면 90%는 이것이 정답입니다.

python3 -m venv .venv
source .venv/bin/activate   # Windows: .venv\Scripts\activate
pip install requests

예상 정상 결과: 프롬프트 앞에 (.venv)가 붙고, pip install이 아무 경고 없이 완료됩니다. which python을 치면 .../.venv/bin/python 경로가 나옵니다.

• 장점: 시스템 파이썬을 전혀 건드리지 않음, 프로젝트별 버전 고정으로 재현성 확보
• 트레이드오프: 프로젝트를 열 때마다 source .venv/bin/activate로 활성화 필요

만약 python3 -m venv 자체가 ensurepip is not available 오류를 낸다면 Debian/Ubuntu에서는 sudo apt install python3-venv를 먼저 설치해야 합니다.

(b) pipx — CLI 도구 전용

black, httpie, poetry, ruff처럼 명령줄에서 실행하는 도구만 필요하다면 pipx가 최적입니다. 도구마다 독립된 venv를 자동으로 만들어 주기 때문에 의존성 충돌이 없습니다.

sudo apt install pipx      # 또는 brew install pipx
pipx ensurepath
pipx install httpie

pipx ensurepath 실행 후에는 터미널을 새로 열거나 source ~/.bashrc를 해야 PATH가 반영됩니다. 이후 http https://example.com처럼 바로 실행할 수 있습니다.

• 장점: 도구별 격리 자동화, 업그레이드/삭제가 pipx upgrade httpie / pipx uninstall httpie로 깔끔
• 트레이드오프: import용 라이브러리 설치에는 부적합 (실행 파일 전용)

(c) --break-system-packages — 임시/도커 한정

이름 그대로 "시스템 패키지 보호를 깨겠다"는 옵션입니다. 이름값을 하니 신중하게 쓰세요.

pip install --break-system-packages requests

가급적 --user와 조합해 시스템 디렉터리 대신 사용자 홈(~/.local)에 설치하는 편이 그나마 덜 위험합니다.

pip install --user --break-system-packages requests

• 허용되는 상황: 곧 버릴 개인 임시 환경, 도커 이미지 내부
• ⚠️ 금지 상황: 프로덕션 서버의 시스템 파이썬. apt 패키지와 파일이 겹치면 OS 도구가 깨질 수 있습니다.

(d) pip.conf 전역 완화 — 권장하지 않음, 필요할 때만

매번 옵션 치기가 귀찮다면 설정 파일로 상시 완화할 수 있습니다. 다만 안전장치를 항상 꺼두는 것이므로 개인 개발 머신에 한정하세요.

# ~/.config/pip/pip.conf
[global]
break-system-packages = true

• 트레이드오프: PEP 668 보호를 상시 비활성화. 서버·공용 머신에서는 절대 사용 금지

(e) uv — 빠른 최신 개발 환경

Astral이 만든 Rust 기반 도구로, pip/venv를 대체하며 최근 빠르게 채택되고 있습니다. 설치와 의존성 해석 속도가 pip 대비 매우 빠릅니다.

curl -LsSf https://astral.sh/uv/install.sh | sh
uv venv
uv pip install requests

uv venv는 .venv를 자동 생성하고, uv pip install은 그 안에 설치합니다. 별도 activate 없이도 uv run python script.py로 실행할 수 있습니다.

• 장점: 압도적 속도, venv 자동 관리, pyproject.toml 통합
• 트레이드오프: 새 도구 학습 비용, 팀 전체 도입 시 합의 필요

도커/CI 권장 패턴

컨테이너는 그 자체가 격리·일회성 환경이라 접근법이 조금 다릅니다. 정석은 이미지 안에 전용 venv를 만들고 PATH를 잡는 것입니다.

FROM python:3.12-slim

# 전용 venv 생성 후 PATH 선점 → 이후 pip/python은 자동으로 venv 사용
RUN python -m venv /opt/venv
ENV PATH="/opt/venv/bin:$PATH"

COPY requirements.txt .
RUN pip install -r requirements.txt

requirements.txt 예시:

requests==2.32.3

베이스 이미지가 이미 격리 환경이라고 판단되면 pip install --break-system-packages -r requirements.txt도 실무에서 통용됩니다. 다만 venv 패턴이 더 명시적이고 안전합니다.

빌드 실패 분기: CI 로그에 externally-managed-environment가 뜨면 위 두 방법 중 하나로 전환하세요. venv PATH 패턴을 우선 적용하고, 그래도 특수한 베이스 이미지 문제로 막히면 --break-system-packages로 우회하는 순서를 추천합니다.

절대 하지 말 것

편해 보이지만 시스템을 망가뜨리는 두 가지입니다.

• sudo pip install ...: apt가 관리하는 파일과 pip가 설치한 파일이 같은 경로에서 충돌합니다. 이 상태에서 apt 업데이트가 돌면 의존성이 꼬여 apt 자체나 시스템 유틸리티가 동작하지 않을 수 있습니다.
• EXTERNALLY-MANAGED 파일 수동 삭제: 당장은 pip가 통과하지만, 이는 안전장치를 영구 제거하는 행위입니다. 이후 OS 업데이트로 시스템 파이썬 패키지가 갱신될 때 pip가 설치한 패키지와 충돌해 시스템 파이썬이 붕괴할 위험이 있습니다.

두 방법 모두 "당장은 되는 것처럼 보이지만 나중에 시스템 전체를 인질로 잡는" 유형이라는 점을 기억하세요.

결론 — 상황별 1줄 추천

• 프로젝트 개발 → python3 -m venv .venv (표준·안전)
• CLI 도구만 → pipx install 도구명
• 속도가 중요 → uv venv + uv pip install
• 도커/CI → 이미지 내 전용 venv + PATH 선점
• 정말 임시/일회성 → pip install --user --break-system-packages

그리고 다시 한 번, sudo pip install과 EXTERNALLY-MANAGED 파일 삭제는 절대 하지 마세요. 30초만 투자해 판정표에서 내 상황을 고르면, 시스템을 지키면서도 원하는 패키지를 안전하게 설치할 수 있습니다.

다음 편에서는 이렇게 만든 venv/uv 환경을 팀 전체가 재현 가능하게 만드는 방법, 즉 pyproject.toml과 lock 파일로 의존성을 고정하는 실전 워크플로를 다룹니다.

자주 묻는 질문 (FAQ)

Q. --break-system-packages를 쓰면 진짜 시스템이 망가지나요? A. 한 번 쓴다고 즉시 망가지지는 않습니다. 위험은 pip가 설치한 패키지가 apt/brew가 관리하는 같은 이름의 패키지와 충돌할 때 발생합니다. 개인 임시 환경이나 도커라면 실용적으로 쓸 수 있지만, 프로덕션 서버의 시스템 파이썬에는 사용하지 마세요.

Q. venv와 pipx 중 뭘 써야 하나요? A. 코드에서 import할 라이브러리(requests, pandas 등)를 쓰려면 venv, black이나 httpie처럼 터미널에서 실행하는 명령줄 도구만 필요하면 pipx입니다. 둘은 배타적이지 않으니 상황에 맞게 병행해도 됩니다.

Q. 그냥 예전처럼 쓰고 싶은데 EXTERNALLY-MANAGED 파일을 지우면 안 되나요? A. 지우지 마세요. 안전장치를 영구히 제거하는 것이라 이후 OS 업데이트 때 시스템 파이썬이 깨질 수 있습니다. 예전 방식이 그리우면 개인 머신에 한해 pip.conf에 break-system-packages = true를 설정하는 편이 그나마 되돌리기 쉬운 선택입니다.