externally-managed-environment 오류가 나오면 시스템 Python에 전역으로 설치하려는 상황인지 먼저 확인해야 합니다. 프로젝트 라이브러리는 venv, 독립 실행 CLI는 pipx, 운영체제가 관리하는 패키지는 apt·dnf·brew 같은 OS 패키지 관리자를 선택하는 것이 기본 방향입니다. 이 글에서는 그 구분과 현재 어떤 Python을 쓰고 있는지 확인하는 방법까지 정리합니다.
오류가 의미하는 것
PEP 668은 Python 환경이 운영체제나 다른 배포 도구의 관리 대상임을 EXTERNALLY-MANAGED 표시로 알릴 수 있게 합니다. 이런 환경에서 pip가 시스템 영역을 직접 바꾸면 OS가 관리하는 Python 패키지와 충돌할 수 있으므로, pip는 설치를 멈추고 별도 환경을 사용하라는 안내를 보여줄 수 있습니다.
따라서 이 오류는 패키지 이름이 틀렸다는 뜻이라기보다 설치 위치를 다시 선택하라는 신호에 가깝습니다. --break-system-packages는 이 보호를 무시하는 예외적 선택이므로, 시스템 Python을 계속 관리해야 할 분명한 이유와 복구 방법이 있을 때만 검토하는 편이 안전합니다.
설치 대상별 선택 기준
프로젝트에서 import할 라이브러리: venv
애플리케이션 코드가 라이브러리를 import한다면 프로젝트마다 가상환경을 만드는 것이 맞습니다. Python 공식 문서의 venv는 인터프리터·라이브러리·실행 파일을 별도 환경에 담고, 그 환경의 패키지를 다른 가상환경 및 운영체제 Python 패키지와 기본적으로 격리합니다.
python3 -m venv .venv
source .venv/bin/activate
python -m pip install requests
Windows에서는 활성화 명령이 다르므로 운영체제에 맞는 방법을 사용합니다. 핵심은 pip만 따로 호출하지 않고 선택한 Python에 연결된 python -m pip를 사용하는 것입니다.
독립 실행 CLI: pipx
black, ruff처럼 프로젝트 코드가 import하는 라이브러리가 아니라 터미널에서 직접 실행하는 Python 애플리케이션은 pipx가 더 잘 맞습니다. pipx는 CLI마다 격리된 환경을 사용하면서 실행 명령을 노출하므로, 여러 도구의 의존성이 한 프로젝트 환경에서 섞이는 일을 줄일 수 있습니다.
pipx 자체의 설치 방법과 PATH 설정은 운영체제별 공식 안내를 먼저 확인해야 합니다. 설치 뒤 command not found가 나오면 패키지를 다시 설치하기 전에 pipx의 실행 파일 경로가 PATH에 들어갔는지 확인합니다.
OS가 관리할 구성요소: apt·dnf·brew
운영체제와 함께 관리해야 하는 런타임이나 애플리케이션은 해당 배포판의 패키지 관리자를 우선 봅니다. Ubuntu·Debian 계열은 apt, Fedora 계열은 dnf, Homebrew가 제공하는 런타임·애플리케이션은 brew가 담당하는 영역입니다. 배포판과 버전에 따라 패키지명과 명령이 달라질 수 있으므로 사용 중인 OS의 공식 패키지 목록을 확인하는 편이 정확합니다.
Homebrew 공식 문서도 기본 Python에 프로젝트 의존성을 직접 설치하지 말고 virtual environment를 사용하며, 독립 Python CLI에는 pipx를 사용하도록 안내합니다. brew와 pip는 경쟁하는 설치 명령이 아니라 관리 대상이 다른 도구입니다.
가상환경을 만들었는데도 오류가 날 때
가상환경을 만들었다는 사실보다 지금 실행한 Python이 어느 환경에 속하는지가 중요합니다. 다음 명령으로 경로와 prefix를 함께 확인합니다.
python -c "import sys; print(sys.executable); print(sys.prefix); print(sys.base_prefix)"
python -m pip --version
가상환경에서는 sys.prefix가 sys.base_prefix와 달라지는 것이 판별 기준입니다. sys.executable이 .venv 아래를 가리키지 않거나 python -m pip --version의 경로가 시스템 영역이라면, 활성화가 빠졌거나 다른 Python을 호출하고 있는 것입니다. 셸에서 가상환경을 다시 활성화한 뒤 동일한 명령으로 재확인합니다.
저라면 이렇게 결정합니다
설치 전에 패키지가 코드에서 import될지, 터미널 명령으로만 실행될지, OS 구성요소로 관리될지를 먼저 적습니다. import 대상이면 프로젝트의 venv, 독립 CLI면 pipx, OS가 책임져야 할 구성요소면 apt·dnf·brew를 선택합니다. 그 다음 sys.executable과 python -m pip --version으로 선택이 실제 실행 환경에 반영됐는지 확인합니다.
이 순서를 지키면 오류 메시지를 없애는 데만 집중하지 않고 다음 업데이트 때 어떤 도구가 패키지를 관리하는지도 분명해집니다. 다음으로는 venv를 만들었는데도 pip가 시스템 Python을 가리키는 경우, 또는 pipx 설치 후 명령을 찾지 못하는 경우를 따로 점검하면 됩니다.