pip: error: externally-managed-environment

안녕하세요, BlueByte입니다. 새로 올린 Ubuntu 24.04나 Debian 12 서버에서 pip3 install requests를 치면 다운로드 대신 error: externally-managed-environment와 함께 apt·venv·pipx를 권하는 긴 문단이 나옵니다. 고장 난 것도, pip이 이상해진 것도 아닙니다. 배포판이 자기 Python을 OS 패키지 관리자 소유로 표시했고, pip은 PEP 668이 요구하는 대로 그 표시를 존중하고 있을 뿐입니다. 오늘은 이 메시지가 어디서 오는지, 왜 sudo와 --user로는 못 넘어가는지, 지원되는 설치 경로 세 가지, 우회 옵션이 허용되는 경우, 그리고 제대로 된 인터프리터에 들어갔는지 확인하는 법까지 하나씩 짚어보겠습니다.

오류 메시지의 생김새와 각 줄을 누가 썼는지

Ubuntu 24.04, Python 3.12에서의 전체 출력입니다:

$ pip3 install requests
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.
 
    If you wish to install a non-Debian packaged Python application,
    it may be easiest to use pipx install xyz, which will manage a
    virtual environment for you. Make sure you have pipx installed.
 
    See /usr/share/doc/python3.12/README.venv for more information.
 
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이 직접 쓴 줄은 첫 줄과 note:, hint:뿐입니다. 들여쓰기된 문단은 배포판이 함께 배포하는 파일에서 그대로 복사한 것이라, Debian·Fedora·Arch·Homebrew마다 문구가 다릅니다. sudo pip3 install도 pip3 install --user도 같은 메시지를 냅니다. 이 표시를 처음 존중한 버전이 pip 23.0이라, 이전 배포판 릴리스에서 업그레이드한 서버는 어느 날 갑자기 거부하기 시작합니다.

거부를 켜는 마커 파일

PEP 668은 인터프리터의 표준 라이브러리 디렉터리에 EXTERNALLY-MANAGED라는 파일 하나를 정의합니다. pip은 두 조건이 동시에 참일 때 거부합니다. 그 파일이 존재하고, 가상환경 밖(sys.prefix == sys.base_prefix)이라는 조건입니다. 직접 확인해 보면:

STDLIB=$(python3 -c 'import sysconfig; print(sysconfig.get_path("stdlib"))')
cat "$STDLIB/EXTERNALLY-MANAGED"

[externally-managed]
Error=To install Python packages system-wide, try apt install
 python3-xyz, where xyz is the package you are trying to
 install.
 ...

단순한 INI 파일이고, Error 키의 값이 pip이 출력한 그 문단입니다. Ubuntu에서는 이 파일이 libpython3.12-stdlib 패키지 소유라서, 지워도 다음 Python 보안 업데이트가 되살려 놓습니다. Debian 릴리스 노트가 의도를 설명합니다. apt가 함께 배포하는 라이브러리를 pip uninstall하거나 업그레이드하면 apt 소유 파일이 지워질 수 있고, Ubuntu에서 그 인터프리터 위에서 도는 도구에는 unattended-upgrade와 cloud-init이 포함됩니다. 이 거부는 바로 그것을 지키기 위한 장치입니다.

sudo와 --user가 통하지 않는 이유

두 경로 모두 시스템 인터프리터의 sys.path에 패키지를 놓습니다. root는 /usr/lib/python3/dist-packages, --user는 ~/.local/lib/python3.12/site-packages인데, 둘 다 apt가 관리하는 모듈을 똑같이 가리거나 충돌시키므로 PEP 668은 둘 다 의도적으로 막습니다. 여기엔 고칠 권한 문제가 없습니다. 인터프리터를 잘못 겨눈 것이고, 아래는 전부 올바른 인터프리터를 고르는 이야기입니다.

프로젝트 의존성이라면: 가상환경

venv는 자체 sys.prefix를 가지므로 그 안의 pip은 마커를 아예 보지 않습니다:

python3 -m venv .venv
source .venv/bin/activate
python -m pip install requests

Installing collected packages: urllib3, idna, charset_normalizer, certifi, requests
Successfully installed certifi-2026.7.22 charset_normalizer-3.5.1 idna-3.19 requests-2.34.2 urllib3-2.8.0

activate가 필수는 아닙니다. .venv/bin/pip install requests와 .venv/bin/python app.py처럼 경로로 바로 실행할 수 있고, cron이나 systemd 유닛에서는 이쪽이 오히려 안전합니다. python3 -m venv가 ensurepip is not available이라며 실패하면 venv 모듈이 아직 없는 것이니 sudo apt install python3-venv(메시지가 권하는 대로 python3-full도 가능)로 해결됩니다.

도구는 pipx, OS가 직접 쓰는 스크립트는 apt

import해서 쓰는 게 아니라 실행하는 것들, 예를 들어 black·ansible·httpie는 pipx가 애플리케이션마다 venv를 하나씩 만들고 실행 파일을 PATH에 올려 줍니다:

sudo apt install pipx
pipx ensurepath
pipx install black

pipx는 설치한 패키지와 노출한 앱 이름을 출력합니다. ensurepath 뒤에는 새 셸을 열어야 ~/.local/bin이 PATH에 잡힙니다. 도구마다 독립적으로 업그레이드·삭제되고, 서로를 망가뜨릴 수 없습니다.

반대로 /usr/bin/python3로 root 권한에서 도는 스크립트(모니터링 훅, 백업 작업 등)가 import하는 모듈이라면, 정직한 답은 배포판 패키지입니다. 그래야 보안 업데이트도 apt가 같이 챙깁니다:

apt-cache policy python3-requests
sudo apt install python3-requests

우회 옵션과 그것이 실제로 감수하는 위험

pip의 비상구는 --break-system-packages(환경변수로는 PIP_BREAK_SYSTEM_PACKAGES=1)입니다. 이름이 이런 데는 이유가 있습니다. 패키징 명세는 이 플래그가 "위험하다는 뉘앙스를 담도록" 설치 도구에 요구합니다. ubuntu:24.04로 만든 일회용 컨테이너처럼 이미지 자체를 버리는 환경이라면 변명이 되는 지름길이지만, 오래 운영하는 서버에서는 훗날의 pip install --upgrade가 unattended-upgrade가 의존하는 모듈을 바꿔치기할 수 있고, 그 사실은 다음 패치 시간에 드러납니다. Homebrew 문서도 macOS에서 같은 경고를 하며, 기본 인터프리터에 pip install --upgrade pip을 하지 말라고 못 박습니다.

실제 사례: Ubuntu 24.04로 옮긴 뒤의 cron 리포트 스크립트

22.04에서 pip3 install --user requests openpyxl로 몇 년을 돌던 야간 리포트가 있었습니다. 24.04에 다시 세우자 첫 pip3 install --user가 위 문구로 거부됐고, cat /usr/lib/python3.12/EXTERNALLY-MANAGED로 마커를 확인했습니다. 해결은 스크립트 옆에 venv를 두고 crontab에서 경로로 호출하는 것이었습니다:

sudo python3 -m venv /opt/report/.venv
sudo /opt/report/.venv/bin/pip install -r /opt/report/requirements.txt

# /etc/cron.d/report
15 2 * * * report /opt/report/.venv/bin/python /opt/report/run.py

스크립트는 한 줄도 바꾸지 않고 돌았고, apt는 /opt를 건드리지 않으므로 venv는 다음 Python 보안 업데이트에도 살아남습니다.

인터프리터를 확인하고, 그 상태를 유지하기

이후에 생기는 문제 대부분은 한 인터프리터에 설치하고 다른 인터프리터로 실행하는 경우입니다. Python에게 직접 물어보세요:

.venv/bin/python -c 'import sys, requests; print(sys.prefix != sys.base_prefix, requests.__version__)'
.venv/bin/pip --version

True 2.34.2
pip 24.0 from /home/you/app/.venv/lib/python3.12/site-packages/pip (python 3.12)

True면 가상환경이고, pip 경로가 .venv 아래면 설치가 실행 위치로 갑니다. 이 상태를 유지하려면 프로젝트마다 requirements.txt와 venv를 두고, 서비스는 activate에 기대지 말고 .venv/bin/python 절대 경로를 가리키게 하세요. 마커 파일은 그냥 두십시오. 어차피 apt가 되돌려 놓습니다. Dockerfile에서는 공식 python:3.12 이미지를 쓰거나(직접 python:3.12-slim을 확인해 보니 표준 라이브러리 디렉터리에 마커가 없었습니다) 이미지 안에 venv를 만드세요. 시스템 pip을 pip으로 업그레이드하지 마십시오.

EACCES·ModuleNotFoundError와 어떻게 다른지

/usr/lib/python3/dist-packages에 대한 PermissionError: [Errno 13] Permission denied는 파일 시스템 권한 문제이고 pip 메시지에도 경로가 찍힙니다. 마커 오류는 경로를 전혀 언급하지 않습니다. 설치가 성공했는데 나오는 ModuleNotFoundError: No module named 'requests'는 정반대 상황입니다. 설치는 됐지만 스크립트를 돌리는 인터프리터가 다른 것이고, which python과 스크립트의 shebang을 비교하면 풀립니다. 다음에 이 오류를 만나면 질문을 거꾸로 따라가 보세요. 어느 인터프리터인지, 어떤 종류의 패키지인지, 지원되는 세 경로 중 어디에 해당하는지.