자동 실행 검증 A · Ubuntu 26.04 · Python 3.14.4 · cowsay 6.1 · 2026-11-04게시 2026-11-03최종 확인 2026-11-04읽기 4분

pip externally-managed-environment 오류 해결: venv로 설치하기

pip install이 externally-managed-environment로 막힐 때 원인(PEP 668)과 해결법. --break-system-packages 대신 venv를 만들어 설치하는 과정을 실행 로그로 확인했다.

30초 요약

  • --break-system-packages로 우회하지 말고 가상환경(venv)을 만들어 그 안의 pip로 설치한다. 오류가 사라지고 시스템 파이썬도 건드리지 않는다.
  • 오류의 원인은 pip가 아니라 시스템 파이썬의 stdlib 디렉터리에 놓인 EXTERNALLY-MANAGED 파일이다.
  • 명령은 python3 -m venv .venv → .venv/bin/pip install 패키지 두 줄이면 된다.

증상/목표

스크립트에 필요한 패키지를 설치하려고 pip install을 쳤는데 다음 오류로 멈췄다.

error: externally-managed-environment

검색하면 --break-system-packages를 붙이라는 답이 먼저 나온다. 목표는 그 옵션 없이 같은 패키지를 설치해 쓰는 것이다.

원인

배포판은 시스템 파이썬의 stdlib 디렉터리에 EXTERNALLY-MANAGED 파일을 둘 수 있다. pip 같은 설치 도구는 가상환경 밖에서 실행될 때 이 파일을 찾고, 있으면 설치를 거부한다. 파일은 INI 형식이며 [externally-managed] 섹션과 Error 키를 갖고, Error의 내용이 오류 메시지로 나온다. 위치는 sysconfig.get_path("stdlib", sysconfig.get_default_scheme())가 가리키는 디렉터리다.

배포판이 패키지 관리자(apt 등)로 설치한 파이썬 패키지를 pip가 덮어써서 시스템 도구가 깨지는 일을 막으려는 장치다. 가상환경 안에서는 검사 조건(“가상환경 밖에서 실행 중인가”)이 맞지 않으므로 파일이 있어도 적용되지 않는다.

해결 방법

1. 마커 파일 확인하기

원인이 맞는지 시스템 파이썬에서 파일 위치를 찾는다.

Terminal window
/usr/bin/python3 -c 'import sysconfig, os; print(os.path.join(sysconfig.get_path("stdlib", sysconfig.get_default_scheme()), "EXTERNALLY-MANAGED"))'

출력된 경로에 파일이 있으면 이 오류가 맞다.

2. 가상환경 만들기

프로젝트 폴더에서 venv를 만든다. 데비안·우분투 계열에서 venv 모듈이 없다는 오류가 나면 python3-venv 패키지를 설치한다.

Terminal window
python3 -m venv .venv

3. venv의 pip로 설치하기

활성화하지 않고 경로로 바로 부르면 된다.

Terminal window
.venv/bin/pip install cowsay
.venv/bin/python -c "import cowsay"

스크립트도 .venv/bin/python script.py로 실행한다. 활성화 없이 실행하는 방법은 venv 활성화 없이 스크립트 실행하기에 정리했다.

4. 명령줄 도구라면 pipx

PEP 668은 배포판이 pipx를 패키지로 제공하고 오류 메시지에서 안내하도록 권한다. pipx는 앱마다 가상환경을 자동으로 만들어 준다.

5. 그래도 시스템에 직접 설치해야 한다면

--break-system-packages는 검사를 넘기는 옵션이다. PEP 668은 이런 우회 옵션이 기본으로 켜져서는 안 되고 위험하다는 뜻을 담아야 한다고 쓴다. 쓴다면 시스템 파이썬을 망가뜨릴 수 있음을 알고 쓴다.

--break-system-packages 대신 venv의 pip로 설치한다

  • 할 것: python3 -m venv .venv로 가상환경 만들기 · .venv/bin/pip install로 설치하기 · 명령줄 도구는 pipx로 설치하기
  • 하지 말 것: --break-system-packages를 습관처럼 붙이기 · EXTERNALLY-MANAGED 파일 지우기 · .venv를 저장소에 올리기

확인

검증 범위: 시스템 파이썬의 EXTERNALLY-MANAGED 파일 확인, 수정 전 오류 재현, venv 설치와 시스템 파이썬 비오염은 GitHub 호스티드 우분투 러너에서 실행으로 확인했다. 검증 러너(Ubuntu 26.04) 이미지는 pip 설정으로 시스템 패키지 보호를 꺼 두고 있어, 그 설정을 비운 기본 상태에서 오류를 재현했다. pipx와 --break-system-packages 동작은 PEP 668 문서로 대조했다.

CI 실행 결과 · 수정 전 재현 1건 · 수정 후 8/8 단계 성공
검증 환경 4항목
OSUbuntu 26.04.1
Python3.14.4
cowsay6.1
실행 날짜2026-11-04
실행 기록
[PASS] 시스템 파이썬 경로가 있다
[PASS] EXTERNALLY-MANAGED 경로를 얻었다
[PASS] stdlib 디렉터리에 EXTERNALLY-MANAGED 파일이 있다
[PASS] 파일에 [externally-managed] 섹션이 있다
[진단] pip 설정에 break-system-packages가 있는가: 있음
[진단] 환경 변수 PIP_BREAK_SYSTEM_PACKAGES가 있는가: 없음
수정 전 재현 · 예상된 실패 1건 재현됨수정 전: 시스템 파이썬의 pip로 패키지를 설치한다 (러너의 pip 설정·환경 변수를 비운 기본 상태)
[XFAIL] 시스템 pip로 cowsay 설치 — 예상된 실패 재현됨 (/externally-managed-environment/)
    > error: externally-managed-environment
수정 후 확인 · 4/4 단계 성공수정 후: 가상환경을 만들어 그 안의 pip로 설치한다
[PASS] venv 생성
Collecting cowsay
  Downloading cowsay-6.1-py3-none-any.whl.metadata (5.6 kB)
Downloading cowsay-6.1-py3-none-any.whl (25 kB)
Installing collected packages: cowsay
Successfully installed cowsay-6.1
[PASS] venv의 pip로 cowsay 설치
[PASS] venv 파이썬에서 cowsay를 불러온다
[PASS] 시스템 파이썬에는 cowsay가 설치되지 않았다
이 결과는 글의 명령어를 GitHub Actions의 깨끗한 환경에서 그대로 실행해 자동으로 붙인 것입니다.

주의

  • venv를 만들지 않고 --break-system-packages를 습관처럼 붙이면 apt로 설치된 파이썬 패키지와 pip 패키지가 섞인다. 시스템 도구가 쓰는 패키지가 바뀌면 그 도구가 깨질 수 있다.
  • EXTERNALLY-MANAGED 파일을 지우는 방법은 권하지 않는다. 배포판 업데이트로 다시 생길 수 있고, 같은 위험이 남는다.
  • .venv는 저장소에 올리지 않는다. .gitignore에 넣고 requirements.txt로 패키지 목록을 관리한다.

자주 묻는 질문

pip에서 externally-managed-environment가 나오는 이유는 무엇인가?

시스템 파이썬의 stdlib 디렉터리에 배포판이 둔 EXTERNALLY-MANAGED 파일이 있고, pip가 가상환경 밖에서 실행됐기 때문이다. 가상환경 안에서는 이 검사가 적용되지 않는다.

venv를 활성화하지 않아도 되는가?

된다. .venv/bin/pip와 .venv/bin/python을 경로로 직접 부르면 그 가상환경 기준으로 동작한다.

--break-system-packages는 언제 쓰는가?

격리된 일회용 컨테이너처럼 시스템 파이썬이 망가져도 상관없는 환경에서만 쓴다. 일반 개발 환경에서는 venv가 낫다.

참고 자료