파이썬으로 자동화 스크립트를 하나 돌려보려다가 pip install 한 줄에서 30분을 날려본 적 있으실 겁니다. 권한 거부, 버전 충돌, 빌드 실패, SSL 오류까지 메시지는 매번 다른데 검색해서 나오는 답은 “관리자 권한으로 실행하세요” 같은 위험한 조언인 경우가 많습니다. 이 글에서는 pip install 오류 해결을 유형별로 정리합니다. 에러 메시지를 보고 어느 갈래인지 3초 안에 판단해서, 그에 맞는 명령 하나로 끝내는 것이 목표입니다.
먼저: 에러 메시지 읽는 법
pip 오류는 화면을 수십 줄 채우지만 실제로 봐야 할 곳은 맨 마지막 두세 줄입니다. 위쪽은 대부분 빌드 로그라서 원인이 아닙니다. 그리고 오류 절반 이상은 “설치가 안 된 것”이 아니라 내가 생각한 파이썬이 아닌 다른 파이썬에 설치된 것입니다.
# 에러 메시지는 아래에서 위로 읽는다. 마지막 줄이 진짜 원인이다.
pip install pandas
# 어떤 파이썬에 설치되는지부터 확인
python -m pip --version
# pip 24.0 from C:\Users\hong\venv\Lib\site-packages\pip (python 3.11)
# pip 명령 대신 항상 이 형태를 쓰는 습관을 들이면 절반은 예방된다
python -m pip install pandasPC에 파이썬이 여러 개 깔려 있으면 pip가 어느 파이썬을 가리키는지 알기 어렵습니다. python -m pip 형태로 쓰면 “지금 이 python에 설치하라”는 뜻이 되어 이 혼란이 사라집니다. 앞으로 나오는 예제도 전부 이 형태를 씁니다.
유형 1. 권한 오류 (Permission denied / Access is denied)
ERROR: Could not install packages due to an OSError: [Errno 13] Permission denied 또는 윈도우에서 Access is denied가 뜨는 경우입니다. 시스템 전체에 설치된 파이썬 폴더에 쓰기를 시도했는데 막힌 상황입니다.
여기서 sudo나 관리자 권한 프롬프트로 다시 실행하는 것이 가장 흔한 대응인데, 이건 문제를 뒤로 미루는 선택입니다. 시스템 파이썬에 패키지가 쌓이면 나중에 프로젝트끼리 버전이 부딪히고, 최악의 경우 OS가 쓰는 파이썬 패키지를 덮어써서 다른 프로그램이 깨집니다.
# 나쁜 예: 시스템 파이썬에 관리자 권한으로 밀어넣기
# sudo pip install requests <- 하지 마세요
# 좋은 예 1) 프로젝트마다 가상환경
python -m venv .venv
# 윈도우
.venv\Scripts\activate
# 맥 / 리눅스
source .venv/bin/activate
python -m pip install requests
# 좋은 예 2) 가상환경을 못 쓰는 상황이라면 사용자 영역에만 설치
python -m pip install --user requests가상환경은 프로젝트 폴더 안에 .venv라는 독립된 파이썬을 만드는 것입니다. 그 안에서는 권한 문제가 아예 생기지 않고, 프로젝트를 지울 때 폴더째 지우면 정리도 끝납니다. 윈도우에서 activate 실행이 막힌다면 별도 설정이 필요한데, 이건 윈도우에서 파이썬 가상환경(venv) 설정 총정리에서 자세히 다뤘습니다.
유형 2. 버전 충돌 (dependency conflict)
설치는 됐는데 빨간 글씨로 이런 경고가 뜨는 경우입니다. ERROR: pip's dependency resolver does not currently take into account all the packages that are installed. A 패키지는 X를 5 미만으로, B 패키지는 5 이상으로 요구하는 상황입니다.
# 무엇이 무엇과 충돌하는지 먼저 확인한다
python -m pip check
# streamlit 1.31.0 has requirement protobuf<5,>=3.20, but you have protobuf 5.26.1.
# 특정 패키지를 누가 요구하는지 역추적
python -m pip show protobuf
# Required-by: grpcio-tools, streamlit
# 해결: 두 패키지를 한 번에 넘겨 resolver가 같이 풀게 한다
python -m pip install "streamlit==1.31.0" "protobuf<5"
# 그래도 안 풀리면 환경을 새로 만드는 편이 빠르다
python -m pip freeze > requirements-old.txt
deactivate
python -m venv .venv-new중요한 건 패키지를 하나씩 따로 설치하지 않는 것입니다. 따로 설치하면 나중에 설치한 것이 앞의 것을 덮어써서 조용히 깨집니다. 충돌하는 패키지들을 한 명령에 같이 넘겨야 pip가 양쪽 조건을 동시에 만족하는 조합을 찾습니다.
충돌이 3개 이상 얽혔다면 푸는 것보다 가상환경을 새로 만들고 필요한 것만 다시 설치하는 편이 대체로 빠릅니다. 기존 환경은 지우지 말고 freeze로 목록만 떠 두세요.
유형 3. 빌드 실패 (Failed building wheel / C++ 필요)
Microsoft Visual C++ 14.0 or greater is required는 파이썬 초보자가 가장 많이 좌절하는 메시지입니다. 하지만 대부분의 경우 C++ 컴파일러를 설치할 필요가 없습니다. 요즘 주요 패키지는 미리 컴파일된 wheel 파일을 제공하는데, pip가 낡았거나 파이썬 버전이 너무 최신이라 그 wheel을 못 찾아 소스 빌드로 넘어간 것뿐입니다.
# 증상: error: Microsoft Visual C++ 14.0 or greater is required
# 또는 error: command 'gcc' failed / Failed building wheel for XXX
# 1) 대부분은 pip / setuptools / wheel 이 낡아서 미리 빌드된 wheel 을 못 받는 것
python -m pip install --upgrade pip setuptools wheel
# 2) 소스 빌드를 아예 막고, 미리 빌드된 wheel 만 받도록 강제
python -m pip install --only-binary=:all: numpy
# 3) 그 패키지가 지금 파이썬 버전용 wheel 을 아직 안 냈을 수 있다
python -V
# Python 3.13.0 <- 새 버전일수록 wheel 이 늦게 올라온다특히 파이썬을 최신 버전으로 막 올린 직후에 이 오류가 몰립니다. numpy, pandas, lxml 같은 패키지는 새 파이썬이 나오고 wheel이 올라오기까지 몇 주에서 몇 달이 걸립니다. 자동화 업무용이라면 최신 버전보다 한 단계 아래 버전을 쓰는 쪽이 훨씬 편합니다.
유형 4. 네트워크·SSL 오류
회사 PC에서 유독 자주 만나는 유형입니다. SSLError, ReadTimeoutError, Could not fetch URL이 여기 해당합니다. 원인은 사내 프록시나 백신의 SSL 검사입니다.
# 증상: Could not fetch URL ... SSLError / ReadTimeoutError
# 사내망, VPN, 백신 SSL 검사 환경에서 흔하다.
# 타임아웃만 늘려서 되는 경우
python -m pip install --timeout 60 pandas
# 사내 프록시를 쓰는 경우
python -m pip install --proxy http://proxy.company.com:8080 pandas
# 사내 인증서 때문에 SSL 검증이 실패하는 경우 (회사 IT가 준 CA 파일 사용)
python -m pip install --cert C:\certs\company-ca.pem pandas검색하면 --trusted-host로 인증서 검증을 꺼버리는 방법이 많이 나오는데, 이건 패키지가 중간에 바뀌어도 알 수 없게 만드는 조치입니다. 회사 IT팀에서 사내 CA 인증서 파일을 받아 --cert로 지정하는 쪽을 먼저 시도하세요.
오류 메시지별 빠른 대조표
| 에러 메시지에 보이는 문구 | 원인 | 먼저 시도할 명령 |
|---|---|---|
| Permission denied / Access is denied | 시스템 폴더 쓰기 권한 없음 | 가상환경 생성 후 재설치, 또는 --user |
| No matching distribution found | 패키지명 오타 또는 파이썬 버전 미지원 | python -V로 버전 확인, 패키지명 재확인 |
| dependency resolver … conflict | 패키지 간 버전 요구 충돌 | python -m pip check 후 함께 설치 |
| Microsoft Visual C++ 14.0 is required | 미리 빌드된 wheel 을 못 찾음 | pip setuptools wheel 업그레이드 |
| SSLError / ReadTimeoutError | 프록시·사내 인증서·네트워크 지연 | --timeout, --proxy, --cert |
| externally-managed-environment | OS 관리 파이썬 보호(우분투·맥 등) | 가상환경 사용 (권장 해결책) |
같은 오류를 두 번 겪지 않으려면
오류를 푸는 것보다 중요한 건 재발을 막는 것입니다. 아래 세 가지만 지켜도 pip 오류의 대부분이 사라집니다.
- 프로젝트마다 가상환경을 만든다. 폴더 하나에
.venv하나. 예외를 두지 않습니다. pip대신python -m pip를 쓴다. 어느 파이썬에 설치되는지 헷갈릴 일이 없어집니다.- 되는 상태를
requirements.txt로 저장한다. 다음에 환경이 깨지면 디버깅 대신 복원으로 끝납니다.
# 되는 환경에서 그대로 떠서
python -m pip freeze > requirements.txt
# 다른 PC에서 똑같이 복원
python -m venv .venv
.venv\Scripts\activate
python -m pip install -r requirements.txt
# requirements.txt 예시 - 버전을 못 박아 두는 것이 핵심
# requests==2.31.0
# pandas==2.2.1
# python-dotenv==1.0.1마지막 항목이 특히 중요합니다. 자동화 스크립트를 다른 PC나 서버에 옮길 때 발생하는 오류의 상당수는, 개발 PC와 실행 PC의 패키지 버전이 다른 데서 옵니다. 버전을 못 박아 두면 이 문제가 통째로 사라집니다.
주의할 점
sudo pip install은 쓰지 않습니다. OS가 쓰는 파이썬 패키지를 덮어써서 시스템 도구가 깨질 수 있습니다.--trusted-host나--break-system-packages는 검증·보호 장치를 끄는 옵션입니다. 원인을 모르는 상태에서 습관적으로 붙이지 마세요.- 설치가 됐는데 import가 안 된다면 그건 설치 문제가 아니라 다른 파이썬을 보고 있는 것입니다.
python -m pip list로 그 파이썬에 정말 있는지부터 확인하세요. - 가상환경 폴더(
.venv)는 깃에 올리지 않습니다..gitignore에 추가하고requirements.txt만 공유합니다.
마무리
지금 작업 중인 프로젝트 폴더에서 python -m venv .venv 한 줄만 실행해 보세요. 1분이면 끝나고, 앞으로 그 프로젝트에서 권한 오류와 버전 충돌은 만나지 않게 됩니다. 이미 꼬여버린 환경이 있다면 python -m pip check로 무엇이 충돌 중인지 확인하는 것부터 시작하면 됩니다.
다음 글에서는 구글 스프레드시트 API를 연동해 흩어진 데이터를 자동으로 모으는 방법을 다루겠습니다.