Python "Could not find a version that satisfies the requirement" 에러: 원인별 진단과 해결 (pip·Poetry)
pip install을 했는데 이런 메시지가 나왔다면, 먼저 이 에러가 무엇을 뜻하는지부터 정확히 알아야 합니다.
ERROR: Could not find a version that satisfies the requirement foo==2.0 (from versions: 1.0, 1.1)
ERROR: No matching distribution found for foo==2.0이 메시지는 pip가 지금 보고 있는 인덱스에서, 요청한 이름·버전 조건·현재 Python 버전·현재 플랫폼을 모두 만족하는 설치 파일(wheel 또는 소스 배포본)을 하나도 찾지 못했다는 뜻입니다. 이름과 달리 대부분은 패키지끼리의 의존성 충돌이 아닙니다. 진짜 충돌은 ResolutionImpossible이라는 다른 에러로 나옵니다(아래 4절).
그래서 해결은 "어떤 조건 때문에 후보가 0개가 됐는가"를 찾는 일입니다. 실제 원인은 대부분 다음 중 하나입니다.
- 패키지 이름 오타, 또는 import 이름과 배포 이름이 다름
- 현재 Python 버전이 그 패키지 버전의 지원 범위(
Requires-Python) 밖 - 내 OS·CPU 아키텍처·Python 버전용 wheel이 없음
- 사설 인덱스·프록시·SSL 문제로 원하는 인덱스를 제대로 못 봄
- pip가 너무 오래돼서 최신 wheel 형식을 인식하지 못함
1. 에러 메시지에서 먼저 볼 곳: (from versions: ...)
괄호 안 목록이 첫 번째 단서입니다.
(from versions: none)→ pip가 쓸 수 있는 파일을 하나도 못 찾았습니다. 이름이 틀렸거나 그 인덱스에 패키지가 없거나, 인덱스 접속 자체가 실패했거나, 내 Python·플랫폼에 맞는 파일이 전혀 없는 경우입니다.- 버전 목록은 나오는데 요청한 버전이 없음 → 요청한 버전이 아예 없거나(예:
2.0.0이 아니라2.0), 있더라도 내 Python 버전이나 플랫폼에는 맞지 않아 후보에서 빠진 경우입니다.
2. 30초 진단 명령
python -V # 지금 쓰는 Python 버전
python -m pip --version # 이 pip가 어느 Python에 붙어 있는지, pip 버전
python -m pip index versions <패키지> # 인덱스에서 보이는 버전 목록 (pip 21.2+, 실험 기능)
python -m pip install -v "<패키지>==<버전>" # 어떤 인덱스를 봤는지, 어떤 파일을 왜 건너뛰었는지
python -m pip download --only-binary=:all: --no-deps "<패키지>==<버전>" # 내 환경용 wheel이 있는지
python -m pip config list # index-url, extra-index-url, proxy, only-binary 설정 확인pip 대신 python -m pip를 쓰면 "pip는 3.8에, python은 3.12에 붙어 있는" 혼동을 피할 수 있습니다. -v 출력에서 특정 파일이 "다른 Python이 필요하다"거나 "wheel 태그가 호환되지 않는다"는 이유로 건너뛰어졌는지 확인하세요. 그 이유가 곧 원인입니다.
3. 원인별 해결
| 원인 | 단서 | 해결 |
|---|---|---|
| ① 이름 오타·배포 이름 다름 | from versions: none, PyPI에서 검색해도 해당 이름이 없음 | 배포 이름으로 설치. 예: import cv2 → opencv-python, import yaml → PyYAML, import PIL → Pillow, import sklearn → scikit-learn |
| ② Python 버전 미지원 | 최신 버전만 목록에서 빠지거나 none. -v에 다른 Python이 필요하다는 메시지 | 지원되는 Python으로 가상환경을 다시 만들거나(py -3.11 -m venv .venv, pyenv 등), 내 Python을 지원하는 이전 버전을 지정 |
| ③ 플랫폼용 wheel 없음 | 새 Python 버전이 나온 직후, Apple Silicon, Alpine(musl), 32비트·ARM Windows 등에서 자주 발생. pip download --only-binary=:all:이 실패 | 그 패키지가 지원하는 Python·플랫폼 사용, Docker라면 Alpine 대신 glibc 기반 이미지(예: python:3.12-slim) 사용. 소스 배포본(sdist)이 있으면 빌드 도구를 설치해 소스 빌드도 가능 |
| ④ 인덱스·프록시·SSL | pip config list에 사설 index-url, -v에 접속 오류(SSL, Proxy, 401/403) | 올바른 index-url 지정, --proxy 설정, 사내 CA는 --cert <ca.pem>(또는 PIP_CERT). --trusted-host는 TLS 검증을 끄므로 최후의 수단 |
| ⑤ 오래된 pip | 다른 PC에서는 설치되는데 이 환경만 실패, pip 버전이 낮음 | python -m pip install --upgrade pip 후 재시도. 오래된 pip는 manylinux_2_28, musllinux 같은 최신 wheel 태그를 인식하지 못해 호환 wheel을 건너뜀 |
설정 파일이나 환경 변수에 only-binary가 걸려 있으면 wheel 없이 소스 배포본만 있는 패키지도 같은 에러를 냅니다. pip config list와 env | grep -i pip로 함께 확인하세요.
사설 인덱스를 extra-index-url로 PyPI와 섞어 쓰면, 같은 이름의 패키지가 양쪽에 있을 때 의도하지 않은 쪽이 설치될 수 있습니다(의존성 혼동 공격). 사내 패키지는 사설 인덱스 하나로 프록시하는 구성이 안전합니다.
4. 진짜 의존성 충돌은 ResolutionImpossible로 나온다
pip 20.3부터는 백트래킹 resolver가 기본이라, 패키지끼리 요구 버전이 겹치지 않으면 설치 단계에서 충돌을 감지해 이렇게 알려 줍니다.
ERROR: Cannot install package-a==1.0 and package-b==2.0 because these package versions have conflicting dependencies.
ERROR: ResolutionImpossible: for help visit https://pip.pypa.io/en/latest/topics/dependency-resolution/#dealing-with-dependency-conflicts이 경우는 원인과 해결 순서가 다릅니다. pip ResolutionImpossible 의존성 충돌 에러 해결법을 참고하세요. 이미 설치된 환경의 의존 관계를 볼 때는 pipdeptree가 유용합니다.
python -m pip install pipdeptree
pipdeptree # 설치된 패키지의 의존 트리
pipdeptree -r -p requests # requests를 누가 필요로 하는지 역방향으로
python -m pip check # 설치된 패키지 사이의 버전 불일치 점검Poetry에서는 같은 상황이 다른 문구로 나옵니다. Because myproject depends on foo (2.0) which doesn't match any versions, version solving failed.는 위 ①~⑤와 같은 "후보 없음" 문제이고, The current project's supported Python range (...) is not compatible with some of the required packages Python requirement는 pyproject.toml의 Python 범위가 패키지가 지원하는 범위보다 넓어서 생기는 문제입니다. 후자는 프로젝트의 Python 범위를 패키지 요구에 맞게 좁히면 해결됩니다.
5. 재발 방지: 가상환경과 버전 고정
프로젝트마다 가상환경을 따로 두면 다른 프로젝트나 시스템 패키지의 영향을 받지 않습니다. venv는 Python 3.3부터 표준 라이브러리에 포함돼 있습니다.
python3 -m venv .venv
source .venv/bin/activate # macOS/Linux
# .venv\Scripts\activate # Windows (명령 프롬프트)
# .\.venv\Scripts\Activate.ps1 # Windows (PowerShell)
python -m pip install -r requirements.txt
deactivate # 작업이 끝나면버전 고정 방식은 프로젝트 규모에 맞게 고르면 됩니다.
| 항목 | pip + requirements.txt | pip-tools | Poetry |
|---|---|---|---|
| 설정 파일 | requirements.txt (pip freeze로 만든 스냅샷) | requirements.in(직접 의존성) → pip-compile이 만든 고정 requirements.txt | pyproject.toml + poetry.lock |
| 충돌 처리 | 설치할 때 pip resolver가 감지해 ResolutionImpossible로 알림 | pip-compile이 고정 버전 조합을 미리 계산 (pip-tools는 별도 패키지) | poetry lock에서 해결, 실패하면 version solving failed |
| 가상환경 | 직접 만듦 | 직접 만듦 | 자동으로 만들고 관리 |
잠금 파일은 패키지 버전을 고정할 뿐 Python 버전과 플랫폼까지 고정하지는 않습니다. 로컬에서는 되는데 CI나 Docker에서만 이 에러가 난다면, 양쪽의 python -V와 베이스 이미지(Alpine 여부)부터 맞추세요.
환경이 꼬였다고 판단될 때: 가상환경 재생성
deactivate # 활성화돼 있다면
rm -rf .venv # 가상환경 디렉터리 삭제 (프로젝트 폴더 안에서 실행)
python3 -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade pip
python -m pip install -r requirements.txt # 또는 poetry install참고: 공식 문서
- pip: Dependency Resolution
- pip index
- Python Packaging: Platform compatibility tags
- Python 공식 문서: venv
- Poetry: Basic usage
자주 묻는 질문 (FAQ)
Q. (from versions: none)이 나오면 무엇부터 봐야 하나요?
A. 패키지 이름(배포 이름)이 맞는지, python -m pip install -v에서 인덱스 접속이 성공했는지, 그리고 내 Python 버전·플랫폼용 파일이 있는지를 순서대로 확인하세요. 의존성 충돌을 의심하는 것은 그다음입니다.
Q. 로컬에서는 설치되는데 Docker나 CI에서만 실패해요.
A. 대개 Python 버전이나 플랫폼이 다릅니다. CI의 python -V가 로컬과 같은지, 베이스 이미지가 Alpine(musl)이라 wheel이 없는 것은 아닌지 확인하세요. 사내 프록시나 사설 인덱스 설정이 CI에만 없는 경우도 흔합니다.
Q. poetry.lock은 Git에 커밋해야 하나요?
A. 애플리케이션이라면 커밋하세요. 팀원과 CI가 같은 버전 조합을 설치하게 됩니다. 다만 잠금 파일은 Python 버전까지 고정하지 않으므로 pyproject.toml의 Python 범위와 CI의 Python 버전도 함께 맞춰야 합니다.
글마다 출처와 확인 범위가 다릅니다. 아래에 확인일·확인 범위·출처가 기록된 글만 그 범위에서 확인된 것입니다. 기록이 없는 글은 적용 전 사용 중인 버전의 공식 문서로 직접 확인하고, 오류는 이메일로 알려주세요. 편집 정책 · 이메일로 제보
이 글에는 사람이 확인한 날짜·범위 기록이 아직 없습니다.
댓글
첫 번째 댓글을 남겨보세요.