개발 오류 해결

pip externally-managed-environment 오류 해결: venv·pipx 정리

치현AI 2026. 11. 19. 09:10

pip install 했는데 error: externally-managed-environment가 나오면, 시스템 파이썬에 직접 설치하지 말고 가상환경(venv)을 만들어 그 안에 설치하면 됩니다. 명령은 세 줄입니다.

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

명령줄 프로그램(예: black, httpie)을 쓰려는 것이라면 pipx install 패키지이름이 더 편합니다. --break-system-packages는 오류를 없애 주지만 운영체제 패키지를 망가뜨릴 수 있어 권하지 않습니다. 아래 내용은 2026년 11월 18일에 리눅스(우분투 24.04)에서 파이썬 3.12와 pip 24.0으로 직접 실행해 확인한 결과입니다.

1. 오류 원문과 언제 나오는지

우분투의 시스템 파이썬(/usr/bin/python3.12)으로 pip 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.
    ...
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.

원인은 파이썬 폴더 안의 EXTERNALLY-MANAGED라는 표시 파일입니다. 이 환경에서는 /usr/lib/python3.12/EXTERNALLY-MANAGED에 있었고, 안에 위 안내문이 그대로 들어 있었습니다. 이 파일이 있으면 pip는 "이 파이썬은 apt가 관리한다"고 보고 설치를 거부합니다(PEP 668). 우분투 23.04, 데비안 12부터 이 파일이 들어가서, 예전 글대로 pip install만 치면 이 오류를 만나게 됩니다.

pip install --user로 바꿔도 결과는 같았습니다. 같은 error: externally-managed-environment가 나옵니다.

윈도우에서는 해당 없음

python.org 설치본으로 윈도우에 설치한 파이썬에는 이 표시 파일이 들어가지 않아서, 윈도우 명령 프롬프트나 PowerShell에서는 이 오류가 보통 나오지 않습니다. 윈도우 PC라도 WSL(우분투) 안에서 pip를 쓰면 리눅스와 똑같이 나옵니다. 맥의 Homebrew 파이썬에서도 같은 메시지가 보고되는데, 이 글에서는 맥으로 확인하지 못했습니다.

2. 해결 1: venv 가상환경 (가장 권장)

프로젝트 폴더마다 독립된 파이썬 환경을 만들고 그 안에 설치하는 방법입니다. 직접 실행한 순서입니다.

python3.12 -m venv .venv
source .venv/bin/activate
which python pip
# /tmp/venvtest/.venv/bin/python
# /tmp/venvtest/.venv/bin/pip
pip install requests
# Successfully installed certifi-2026.10.23 charset_normalizer-3.5.2 idna-3.20 requests-2.34.2 urllib3-2.8.0
python -c "import requests; print(requests.__version__)"
# 2.34.2

가상환경 안에는 표시 파일이 없으므로 같은 pip인데도 오류 없이 설치됩니다. deactivate로 빠져나오고, 다음에 작업할 때 source .venv/bin/activate만 다시 하면 됩니다.

  • The virtual environment was not successfully created because ensurepip is not available가 나오면 sudo apt install python3-venv(또는 python3-full)를 먼저 설치합니다.
  • .venv 폴더는 git에 올리지 말고 .gitignore에 넣습니다. 대신 pip freeze > requirements.txt로 목록을 남깁니다.
  • 활성화 없이 .venv/bin/python 스크립트.py처럼 경로로 실행해도 됩니다.

3. 해결 2: 명령줄 도구는 pipx

라이브러리가 아니라 터미널에서 실행하는 프로그램을 설치할 때는 pipx가 맞습니다. 프로그램마다 가상환경을 따로 만들어 주고, 실행 파일만 PATH에 연결합니다. 우분투는 sudo apt install pipx로 설치합니다. 시험 삼아 작은 패키지(pycowsay)를 설치해 봤습니다.

pipx install pycowsay
#   installed package pycowsay 0.0.0.2, installed using Python 3.12.3
# done! ✨ 🌟 ✨
pycowsay hi
#   --
# < hi >
#   --

처음 쓰면 "... is not on your PATH environment variable" 경고가 나올 수 있습니다. 실제로 이 경고가 나왔고, 안내대로 pipx ensurepath를 한 번 실행한 뒤 터미널을 새로 열면 됩니다.

4. 해결 3: apt로 설치

오류 메시지가 처음 권하는 방법입니다. requests라면 sudo apt install python3-requests처럼 python3-를 붙인 이름으로 찾습니다. 다만 배포판 버전이라 최신이 아닐 수 있고, 없는 패키지도 많습니다.

5. --break-system-packages를 쓰면 안 되는 이유

오류 메시지 끝에 나오는 이 옵션을 붙이면 설치는 됩니다. 실제로 --dry-run으로 확인해 보니 Would install certifi-2026.10.23 charset-normalizer-3.5.2 idna-3.20 requests-2.34.2 urllib3-2.8.0처럼 설치 진행 단계로 넘어갔습니다(시스템을 건드리지 않으려고 실제 설치는 하지 않았습니다).

문제는 메시지 원문이 직접 경고하듯 "at the risk of breaking your Python installation or OS"라는 점입니다.

  • apt가 설치한 파이썬 패키지를 pip가 다른 버전으로 덮어쓸 수 있습니다.
  • 우분투의 일부 시스템 도구는 파이썬으로 돌아가서, 의존 패키지 버전이 바뀌면 그 도구가 고장 날 수 있습니다.
  • 나중에 apt 업데이트가 같은 파일을 다시 바꾸면서 충돌이 생길 수 있습니다.

도커 컨테이너처럼 곧 버릴 환경이 아니라면 venv나 pipx가 안전합니다.

6. 한 줄 요약

상황 해결
프로젝트에서 import 할 라이브러리 python3 -m venv .venv 후 그 안에서 pip
터미널에서 실행할 프로그램 pipx install 이름
시스템 파이썬 스크립트용 흔한 패키지 sudo apt install python3-이름
venv 생성 실패(ensurepip) sudo apt install python3-venv
윈도우(python.org 설치본) 보통 이 오류 없음. WSL은 리눅스와 같음

실행 환경: 리눅스(우분투 24.04), 파이썬 3.12.3, pip 24.0, pipx 1.4.3. 윈도우와 맥에서는 직접 실행하지 않았습니다. 초안 작성과 검수에 AI를 사용했고, 명령과 출력은 직접 실행해 대조했습니다.

기준일: 2026-11-18

출처