파이썬에서 externally-managed-environment 오류가 나오면 시스템 Python에 전역으로 설치하려는 상황인지 먼저 확인해야 합니다. 프로젝트 라이브러리는 venv, 독립 실행 도구는 pipx, 운영체제가 관리하는 패키지는 apt나 배포판의 패키지 관리자를 선택하는 것이 기본 방향입니다. python -m pip와 sys.executable로 실제 설치 대상과 실행 중인 Python이 같은 환경인지 확인하면 같은 오류를 반복하는 일도 줄일 수 있습니다.
이 오류는 시스템 Python을 보호하기 위해 발생합니다
PEP 668은 운영체제의 패키지 관리자가 관리하는 Python 환경에 EXTERNALLY-MANAGED marker를 둘 수 있도록 합니다. 이 marker가 있는 기본 환경에서 pip가 전역 설치를 진행하면, 운영체제 패키지와 pip 패키지가 서로 덮어쓰는 문제를 막기 위해 설치가 거부될 수 있습니다. PEP 668의 설명처럼 이 메시지는 pip 자체가 고장 났다는 뜻이라기보다, 현재 설치 위치가 시스템 관리 영역이라는 신호에 가깝습니다.
따라서 오류 메시지를 보고 곧바로 --break-system-packages를 붙이는 것은 첫 해결책으로 적절하지 않습니다. 시스템 Python을 수정하면 운영체제 도구나 이후 업데이트가 영향을 받을 수 있기 때문입니다. 먼저 설치하려는 대상이 무엇인지 나누고, 그 대상에 맞는 환경을 선택하는 순서가 안전합니다.
설치 대상에 따라 venv·pipx·apt를 고르는 기준
프로젝트에서 import할 라이브러리라면 venv
애플리케이션이나 자동화 스크립트가 requests, pydantic처럼 코드에서 import할 패키지를 필요로 한다면 프로젝트 전용 가상환경을 만듭니다. PyPA의 venv 설치 가이드처럼 프로젝트 디렉터리에서 다음과 같이 시작할 수 있습니다.
python3 -m venv .venv
source .venv/bin/activate
python -m pip install 패키지명
가상환경을 쓰는 이유는 프로젝트마다 필요한 버전과 의존성을 분리하기 위해서입니다. 활성화된 셸에서 python -m pip를 사용하면 현재 python이 가리키는 인터프리터의 pip를 호출하므로, 별도의 pip 명령보다 경로가 어긋날 가능성을 줄일 수 있습니다.
독립적으로 실행할 CLI라면 pipx
설치한 패키지를 코드에서 import하는 것이 아니라 명령줄 프로그램으로 사용할 때는 pipx가 맞을 수 있습니다. 예를 들어 하나의 CLI 도구를 여러 프로젝트의 의존성에 섞지 않고 실행하려는 경우입니다. PyPA의 stand-alone command-line tools 안내에 따르면 pipx는 도구별 가상환경을 만들고 실행 파일을 PATH에서 사용할 수 있게 합니다.
다만 pipx가 모든 패키지 설치를 대신하는 것은 아닙니다. 프로젝트 코드가 import해야 하는 라이브러리를 pipx로 설치하면 프로젝트의 .venv와 다른 위치에 들어가므로, 실행 시 ModuleNotFoundError가 날 수 있습니다.
운영체제가 제공하는 패키지라면 apt 또는 배포판 관리자
서버 운영에 필요한 도구나 배포판이 관리하는 Python 모듈을 OS 패키지로 설치해야 한다면 Ubuntu·Debian 계열에서는 apt를 우선 검토합니다. Debian의 Python 운영 안내도 배포판 패키지는 apt, 프로젝트 라이브러리는 가상환경, 독립 애플리케이션은 pipx로 구분하는 방향을 제시합니다.
실제 패키지 이름과 python3-venv 제공 여부는 배포판과 버전에 따라 다를 수 있습니다. 따라서 apt install 명령을 그대로 복사하기보다 사용하는 배포판의 패키지 검색 결과와 공식 안내를 함께 확인해야 합니다.
venv를 만들었는데도 같은 오류가 나면 경로부터 확인합니다
가상환경을 만들었는데 오류가 계속된다면 셸이 여전히 시스템 Python과 pip를 호출하는지 확인해 보십시오. 활성화한 뒤 다음 명령으로 세 경로를 나란히 확인해 보십시오.
which python
python -m pip --version
python -c "import sys; print(sys.executable)"
정상이라면 which python과 sys.executable이 프로젝트의 .venv/bin/python을 가리키고, python -m pip --version 출력에도 같은 .venv 경로가 나타납니다. which pip도 참고할 수 있지만, 실제 설치 인터프리터를 확인하는 데는 python -m pip와 sys.executable을 함께 보는 편이 더 분명합니다.
셸을 활성화하지 않고 실행하는 예약 작업이나 서비스라면 프로젝트의 Python을 직접 지정하는 방식이 안전합니다.
.venv/bin/python -m pip install 패키지명
.venv/bin/python app.py
이렇게 하면 작업을 실행하는 셸의 PATH 설정이 달라도 어느 Python으로 설치하고 실행하는지 명확해집니다.
–break-system-packages는 언제 판단할까요?
이 옵션은 externally managed 보호 장치를 우회하는 선택입니다. 운영체제 패키지와 pip 설치 패키지를 한 환경에서 직접 조정해야 하는 특별한 사정이 있고, 그 영향 범위와 복구 방법을 관리할 수 있을 때만 검토할 대상입니다. 일반적인 프로젝트 개발이나 CLI 설치라면 먼저 .venv 또는 pipx로 분리하는 편이 낫습니다.
판단 순서는 간단합니다.
- 코드에서 import할 프로젝트 의존성인가요? 그렇다면 프로젝트의
venv를 사용합니다. - 독립 실행 명령인가요? 그렇다면 pipx를 검토합니다.
- OS가 관리해야 하는 패키지인가요? 그렇다면 apt나 해당 배포판의 패키지 관리자를 확인합니다.
- 설치 후에는
python -m pip --version과sys.executable로 설치 위치와 실행 위치가 같은지 확인합니다.
이 순서를 지키면 오류 메시지를 억지로 없애는 대신, 패키지의 소유자와 실행 환경을 일치시킬 수 있습니다. 그래도 설치 뒤 ModuleNotFoundError가 발생한다면 패키지를 설치한 Python과 프로그램을 실행한 Python이 같은지부터 다시 확인하는 것이 좋습니다.