pip install 안될 때: 로그 키워드별 원인 진단과 안전한 복구 순서

pip install이 실패하면 같은 명령을 반복하지 말고, 오류 로그가 설치 대상 Python, 권한, 네트워크·TLS, 소스 빌드, 의존성 해결 중 어디를 가리키는지 나눠 확인하세요. 프로젝트 패키지는 sudo pip install 대신 가상환경의 python -m pip으로 설치하는 것이 안전합니다.

설치 대상 Python과 pip가 같은지 확인

pip만 실행하면 셸의 PATH에 먼저 잡힌 pip가 동작합니다. 프로젝트에서 실행할 Python 인터프리터를 기준으로 설치하려면 아래처럼 실행합니다.

python -m pip --version
python -c "import sys; print(sys.executable); print(sys.prefix); print(sys.base_prefix)"

POSIX 환경에서 python 명령이 없다면 python3으로 바꾸고, Windows에서는 py -m pip --version을 사용할 수 있습니다.

출력된 pip 경로와 Python 경로가 프로젝트의 .venv를 가리키지 않는다면 가상환경을 새로 만드세요. sys.prefix와 sys.base_prefix가 다르면 현재 Python은 가상환경에서 실행 중입니다. 가상환경 활성화는 편의 기능이므로, 활성화가 어렵다면 .venv 안의 Python을 직접 실행할 수 있습니다.

# macOS / Linux
python3 -m venv .venv
.venv/bin/python -m pip install --upgrade pip
.venv/bin/python -m pip install somepackage

# Windows PowerShell
py -m venv .venv
.\.venv\Scripts\python.exe -m pip install --upgrade pip
.\.venv\Scripts\python.exe -m pip install somepackage

Python 3.12 이상에서는 새 venv에 setuptools가 기본 포함되지 않습니다. 따라서 모든 설치 실패에 pip setuptools wheel 업그레이드를 일괄 적용하기보다, 우선 pip만 올리고 소스 배포본 빌드 오류가 확인됐을 때 빌드 도구와 빌드 의존성을 추가로 점검하는 편이 정확합니다.

권한 오류와 externally managed 환경

Permission denied 또는 시스템 Python을 수정할 수 없다는 메시지가 보이면 전역 설치를 계속 시도하지 마세요. 최근 Linux 배포판 일부는 EXTERNALLY-MANAGED 표식으로 시스템 Python에 pip가 패키지를 설치·삭제하지 못하게 합니다. 이 경우 배포판 패키지 관리자를 사용하거나 가상환경을 만들어야 합니다.

가상환경 밖에서 개인용 명령행 도구를 설치해야 하는 경우에는 --user를 고려할 수 있습니다.

python3 -m pip install --user somepackage

다만 기본 가상환경 안에서는 --user 설치를 사용할 수 없습니다. 사용자 site-packages가 가상환경의 import 경로에 없어서 설치해도 의미가 없기 때문입니다. 프로젝트 의존성은 --user 대신 해당 프로젝트의 .venv에 설치하세요.

sudo pip install은 시스템 패키지 관리자와 pip의 관리 범위를 섞을 수 있으므로 일반적인 해결책으로 쓰지 않는 것이 좋습니다. 운영 서버에서 시스템 전체 Python 패키지가 필요하다면 배포판 패키지, 컨테이너 또는 별도 가상환경 중 배포 정책에 맞는 방식을 정해야 합니다.

Timeout·프록시·TLS 오류

사내망에서 시간 초과나 연결 실패가 나면 패키지명이나 버전을 바꾸기 전에 프록시 경로를 확인합니다. pip는 --proxy 옵션, 설정 파일의 proxy 값, 표준 환경변수 http_proxy, https_proxy, no_proxy를 지원합니다.

# 한 번의 설치에만 프록시 적용
python -m pip install --proxy http://proxy.example.internal:3128 somepackage

# macOS / Linux: 현재 셸에만 설정
export http_proxy=http://proxy.example.internal:3128
export https_proxy=http://proxy.example.internal:3128
python -m pip install somepackage

# Windows cmd: 현재 창에만 설정
set http_proxy=http://proxy.example.internal:3128
set https_proxy=http://proxy.example.internal:3128
py -m pip install somepackage

프록시가 자체 인증서를 사용해 TLS 검증 오류가 난다면 --trusted-host로 검증을 끄기보다, 조직에서 제공한 CA 번들을 지정해야 합니다.

python -m pip install --cert /path/to/company-ca.pem somepackage

pip는 HTTPS 연결에서 기본적으로 인증서를 검증하며, --cert 또는 PIP_CERT로 별도 CA 번들을 지정할 수 있습니다. 인증서 검증을 우회하면 다운로드 경로의 신뢰 경계가 약해질 수 있습니다.

프록시 주소·인증 정보·사설 인덱스 주소를 CI 로그나 requirements.txt에 평문으로 남기지 마세요. 지속 설정이 필요하다면 python -m pip config debug로 실제로 읽히는 설정 파일과 값을 먼저 확인합니다.

Could not build wheels·컴파일러 오류

휠 빌드 실패를 단순히 wheel 패키지가 없어서 발생한 문제로 보면 안 됩니다. 현재 OS, CPU 아키텍처, Python 버전에 맞는 바이너리 wheel이 없으면 pip가 소스 배포본을 받아 빌드할 수 있고, 이 과정에서 C 컴파일러·Python 개발 헤더·라이브러리 헤더 또는 빌드 백엔드 의존성이 필요할 수 있습니다. pip의 빌드 의존성은 기본적으로 격리된 환경에서 처리되며, --no-build-isolation은 필요한 빌드 의존성을 사용자가 직접 관리할 때만 사용해야 합니다.

먼저 현재 환경에서 바이너리 wheel만 허용했을 때 설치 가능한지 확인합니다.

python -m pip install --only-binary=:all: lxml

이 명령이 실패하면 현재 Python·플랫폼 조합에 맞는 wheel이 없거나, 인덱스에서 해당 wheel을 제공하지 않는 경우를 확인해야 합니다. 이 옵션은 소스 배포본을 금지하므로 wheel이 없는 패키지는 의도적으로 설치에 실패합니다.

소스 빌드가 필요한 것이 확인된 뒤에만 패키지별 공식 설치 문서를 기준으로 OS 의존성을 설치하세요. 예를 들어 lxml을 Debian·Ubuntu에서 소스 빌드할 때는 libxml2와 libxslt의 개발 패키지가 필요할 수 있습니다.

# Debian / Ubuntu 예시 — 시스템 패키지를 변경하므로 배포 정책을 먼저 확인
sudo apt-get update
sudo apt-get install -y build-essential python3-dev libxml2-dev libxslt-dev

# 가상환경의 Python으로 설치
.venv/bin/python -m pip install lxml

이 명령은 lxml용 예시이며, pandas를 포함한 모든 C 확장 패키지에 같은 OS 패키지가 필요한 것은 아닙니다. 패키지와 버전별 빌드 요구 사항을 확인해야 합니다. lxml 공식 문서도 소스 빌드에서는 libxml2와 libxslt 개발 패키지를 요구한다고 안내합니다.

requirements.txt에서 의존성 충돌 찾기

requirements.txt를 한 줄씩 임의로 설치하거나 충돌이 난 패키지를 무조건 고정하면 원인을 가릴 수 있습니다. 깨끗한 가상환경에서 실제 설치 계획을 먼저 계산하고, 충돌하는 직접 의존성의 버전 범위를 확인하세요.

python3 -m venv .venv
.venv/bin/python -m pip install --upgrade pip

# 설치하지 않고 해결 결과를 JSON 파일로 기록
.venv/bin/python -m pip install \
  --dry-run \
  --ignore-installed \
  --report pip-report.json \
  -r requirements.txt

--dry-run은 설치를 수행하지 않고 계획만 출력하며, --report는 설치 또는 설치 예정 항목을 JSON으로 기록합니다. 이 조합은 현재 requirements가 어떤 패키지와 버전을 선택하려 하는지 검토할 때 유용합니다. --report는 pip 22.2에서 추가됐으므로, 오래된 pip에서는 먼저 업그레이드가 필요합니다.

의존성 해결 과정에서 같은 패키지의 여러 버전을 내려받는 것은 pip의 backtracking 동작일 수 있으며, 그 자체가 오류는 아닙니다. ResolutionImpossible처럼 호환 가능한 조합을 찾지 못한 경우에는 최상위 requirements의 버전 범위를 넓히거나 좁히기 전에 각 패키지의 지원 버전과 릴리스 노트를 확인해야 합니다.

설치가 끝난 뒤에는 이미 설치된 패키지 간의 깨진 의존성을 검사합니다.

.venv/bin/python -m pip check

pip check은 설치된 패키지의 요구 의존성이 충족되는지 검사합니다. 해결 실패 자체를 고쳐 주는 명령은 아니지만, 부분 설치나 수동 설치 뒤에 환경이 일관된지 확인하는 데 적합합니다.