requirements.txt 설치 오류 해결: Python 버전과 패키지 충돌 점검법

GitHub 프로젝트나 Python 예제 코드를 내려받은 뒤 가장 자주 실행하는 명령어가 pip install -r requirements.txt입니다. 그런데 같은 프로젝트라도 내 컴퓨터의 Python 버전, 운영체제, 가상환경 상태에 따라 설치가 실패할 수 있습니다.

오류를 빨리 해결하려면 패키지를 하나씩 바꾸기보다 먼저 현재 어떤 Python으로 pip가 실행되는지, requirements.txt에 적힌 패키지 버전이 내 환경과 맞는지, 빌드 도구가 필요한 패키지가 섞여 있는지를 순서대로 확인해야 합니다.

pip install -r requirements.txt 오류는 먼저 Python 버전과 실행 중인 가상환경부터 확인해야 합니다.

requirements.txt 설치 오류가 나는 대표 상황

requirements.txt는 프로젝트 실행에 필요한 패키지 목록을 적어 둔 파일입니다. pip 공식 문서에서도 requirements 파일은 pip install이 설치할 항목 목록으로 설명합니다. 보통 파일 이름은 requirements.txt이지만, 프로젝트에 따라 requirements-dev.txt, requirements-prod.txt처럼 나뉘기도 합니다.

pip install -r requirements.txt

이 명령어가 실패할 때는 단순히 pip가 고장 난 것이 아니라, 아래처럼 프로젝트가 요구하는 조건과 현재 컴퓨터 환경이 맞지 않는 경우가 많습니다.

상황	주요 원인	먼저 볼 것
패키지를 찾지 못함	Python 버전 불일치 또는 잘못된 패키지명	python --version
의존성 충돌	서로 다른 패키지가 다른 버전을 요구	오류 마지막 20줄
wheel 빌드 실패	컴파일 도구 또는 OS별 라이브러리 부족	Failed building wheel
설치는 됐지만 실행 실패	가상환경과 VSCode 인터프리터 불일치	VSCode Python 선택 상태

먼저 확인할 명령어

오류 메시지를 읽기 전에 현재 터미널이 어떤 Python과 pip를 쓰는지 확인해야 합니다. 같은 컴퓨터에 Homebrew Python, pyenv Python, conda Python, Windows Store Python이 함께 있으면 python과 pip가 서로 다른 위치를 가리킬 수 있습니다.

python --version
python -m pip --version
python -m pip list
python -m pip check

Windows에서는 py 런처가 더 정확할 때가 있습니다.

py --version
py -m pip --version
py -m pip check

대표 오류 메시지별 원인

requirements.txt 설치 실패는 오류 메시지 맨 위보다 맨 아래에 원인이 정리되는 경우가 많습니다. 터미널 로그가 길게 올라가더라도 마지막 20~30줄을 먼저 확인하는 것이 좋습니다.

Could not find a version that satisfies the requirement

ERROR: Could not find a version that satisfies the requirement package-name==1.2.3
ERROR: No matching distribution found for package-name==1.2.3

이 메시지는 해당 패키지 버전이 현재 Python, 운영체제, CPU 아키텍처와 맞지 않거나 PyPI에서 찾을 수 없을 때 자주 나옵니다. 예를 들어 프로젝트는 Python 3.10을 기준으로 만들어졌는데 내 환경이 Python 3.13이면 오래된 패키지 버전이 설치되지 않을 수 있습니다.

Failed building wheel

ERROR: Failed building wheel for package-name
ERROR: Could not build wheels for package-name

wheel은 미리 빌드된 설치 파일에 가깝습니다. 내 환경에 맞는 wheel이 없으면 소스에서 직접 빌드하려고 하는데, 이때 C 컴파일러, Rust, Visual Studio Build Tools, Python 헤더, OS 라이브러리 등이 부족하면 실패할 수 있습니다.

subprocess-exited-with-error

error: subprocess-exited-with-error

× Getting requirements to build wheel did not run successfully.
│ exit code: 1

이 메시지는 pip 자체보다 패키지의 빌드 과정에서 실행된 하위 명령이 실패했다는 뜻에 가깝습니다. 바로 requirements.txt를 수정하기보다 어떤 패키지에서 실패했는지 패키지 이름을 먼저 찾아야 합니다.

ResolutionImpossible

ERROR: Cannot install -r requirements.txt because these package versions have conflicting dependencies.
ERROR: ResolutionImpossible

서로 다른 패키지가 동시에 만족할 수 없는 버전을 요구할 때 나타납니다. 예를 들어 A 패키지는 pydantic<2를 요구하고 B 패키지는 pydantic>=2를 요구하면 pip가 조합을 찾지 못할 수 있습니다.

원인 4가지와 해결 방향

1. Python 버전 불일치

가장 먼저 프로젝트 설명 파일을 확인합니다. README.md, pyproject.toml, runtime.txt, .python-version에 권장 Python 버전이 적혀 있을 수 있습니다.

python --version

# pyenv를 쓰는 경우
pyenv versions
pyenv local 3.11.9

# uv를 쓰는 경우
uv python list
uv python install 3.11

패키지 설치 오류가 반복된다면 최신 Python을 쓰는 것보다 프로젝트가 만들어진 Python 버전에 맞추는 편이 안전합니다. 특히 데이터 분석, 머신러닝, 자동화 예제는 특정 Python 버전에 맞춰 requirements.txt가 고정되어 있는 경우가 많습니다.

2. 가상환경 미사용

시스템 Python에 바로 설치하면 기존 패키지와 충돌하거나 권한 문제가 발생할 수 있습니다. Python 공식 문서에서도 가상환경은 특정 애플리케이션에 필요한 패키지를 시스템 전체가 아닌 분리된 환경에 설치하기 위한 방식으로 설명합니다.

# macOS / Linux / WSL
python -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade pip
python -m pip install -r requirements.txt

# Windows PowerShell
py -m venv .venv
.\.venv\Scripts\Activate.ps1
py -m pip install --upgrade pip
py -m pip install -r requirements.txt

macOS나 Linux에서 externally-managed-environment 메시지가 함께 나온다면 시스템 Python 보호 정책과 관련이 있을 수 있습니다. 이 경우에는 시스템 Python에 직접 설치하는 대신 가상환경이나 사용자 환경을 기준으로 설치 위치를 판단하는 것이 좋습니다.

3. 오래된 패키지 버전

requirements.txt에 오래된 버전이 고정되어 있으면 최신 Python에서는 설치되지 않을 수 있습니다.

# 예시
numpy==1.19.5
pandas==1.1.5
scikit-learn==0.24.2

이때 바로 버전을 모두 지우면 프로젝트가 실행되더라도 결과가 달라질 수 있습니다. 먼저 프로젝트가 요구하는 Python 버전을 맞춰 보고, 그래도 실패할 때 특정 패키지만 범위를 완화하는 순서가 좋습니다.

# 수정 전
package-name==1.2.3

# 수정 후보
package-name>=1.2.3,<2.0

4. OS별 빌드 도구 부족

Failed building wheel이 나오면 운영체제별 빌드 도구를 확인해야 합니다. 순수 Python 패키지는 쉽게 설치되지만, C 확장이나 Rust 확장을 포함한 패키지는 OS별 준비가 필요할 수 있습니다.

환경	확인할 항목	예시 명령어
macOS	Xcode Command Line Tools	xcode-select --install
Windows	Visual Studio Build Tools	C++ 빌드 도구 설치 확인
WSL / Ubuntu	컴파일러와 Python 개발 헤더	sudo apt install build-essential python3-dev

빠른 해결 순서

requirements.txt 설치 오류는 Python 버전, 가상환경, 패키지 충돌, 빌드 도구 순서로 좁혀 가면 원인을 찾기 쉽습니다.

처음부터 requirements.txt를 고치기보다 아래 순서대로 좁혀 가면 실패 원인을 찾기 쉽습니다.

1. 프로젝트 폴더에서 실행 중인지 확인합니다.
2. python --version으로 Python 버전을 확인합니다.
3. 새 가상환경을 만들고 활성화합니다.
4. python -m pip install --upgrade pip setuptools wheel을 실행합니다.
5. python -m pip install -r requirements.txt를 다시 실행합니다.
6. 실패한 패키지 이름과 마지막 오류 메시지를 확인합니다.
7. Python 버전 문제인지, 의존성 충돌인지, 빌드 도구 문제인지 분리합니다.

python -m pip install --upgrade pip setuptools wheel
python -m pip install -r requirements.txt

Mac, Windows, WSL에서 다른 점

Mac

macOS에서는 Homebrew Python, pyenv Python, 시스템 Python이 함께 있을 수 있습니다. which python, which pip, python -m pip --version을 함께 확인해야 합니다.

which python
which pip
python -m pip --version

Windows

Windows에서는 python 명령이 Microsoft Store Python으로 연결되거나 PATH 설정에 따라 다른 Python을 가리킬 수 있습니다. 이럴 때는 py -0p로 설치된 Python 목록을 확인하는 것이 좋습니다.

py -0p
py -3.11 -m venv .venv
.\.venv\Scripts\Activate.ps1
py -m pip install -r requirements.txt

WSL

WSL에서는 Linux 환경이므로 Windows에 설치된 Python과 별개로 봐야 합니다. Windows 폴더에 있는 프로젝트를 WSL에서 실행하면 경로와 권한 문제가 섞일 수 있으므로, 가능하면 WSL 홈 디렉터리 아래에서 프로젝트를 관리하는 편이 안정적입니다.

cd ~
git clone 프로젝트주소
cd 프로젝트폴더
python3 -m venv .venv
source .venv/bin/activate
python -m pip install -r requirements.txt

venv, conda, uv 환경별 설치 방법

venv 기준

기본 Python만으로 프로젝트를 실행할 때는 venv가 가장 단순합니다. 프로젝트마다 .venv를 만들면 패키지 충돌을 줄일 수 있습니다.

python -m venv .venv
source .venv/bin/activate
python -m pip install -r requirements.txt

conda 기준

데이터 분석이나 머신러닝 프로젝트에서 conda 환경 파일이 함께 제공된다면 conda를 우선 확인합니다. environment.yml이 있는데 requirements.txt만 설치하면 일부 네이티브 라이브러리가 빠질 수 있습니다.

conda create -n myproject python=3.11
conda activate myproject
python -m pip install -r requirements.txt

uv 기준

uv를 사용한다면 pip와 비슷한 방식으로 requirements.txt를 설치할 수 있습니다. uv 공식 문서에서는 uv pip install -r requirements.txt 형식을 안내하며, 환경을 정확히 맞추고 싶을 때는 uv pip sync requirements.txt도 사용할 수 있습니다.

uv venv
source .venv/bin/activate
uv pip install -r requirements.txt

# lock 파일처럼 환경을 맞추고 싶을 때
uv pip sync requirements.txt

requirements.txt를 수정해도 되는 경우와 안 되는 경우

설치가 실패한다고 해서 requirements.txt를 바로 고치면 안 되는 경우가 있습니다. 특히 회사 프로젝트, 강의 실습, 배포 서버용 파일은 재현성을 위해 버전을 고정해 둔 경우가 많습니다.

상황	수정 가능성	권장 흐름
개인 실습 프로젝트	상대적으로 가능	한 패키지씩 범위 완화
강의·책 예제	주의 필요	저자가 안내한 Python 버전 확인
회사·배포 프로젝트	임의 수정 지양	팀 기준 또는 lock 파일 확인

수정이 필요하다면 전체 버전을 한 번에 지우기보다 실패한 패키지만 바꾸고, 설치 후 python -m pip check로 충돌이 남아 있는지 확인합니다.

python -m pip check
python -m pip freeze > requirements-fixed.txt

재발 방지 체크리스트

• 프로젝트마다 .venv 또는 conda 환경을 따로 만듭니다.
• pip 단독 명령보다 python -m pip 형식을 우선 사용합니다.
• README에 권장 Python 버전이 있는지 먼저 확인합니다.
• 설치 전 python --version과 python -m pip --version을 확인합니다.
• 오류가 나면 마지막 오류 메시지와 실패한 패키지 이름을 따로 기록합니다.
• requirements.txt를 수정했다면 원본을 백업합니다.
• VSCode를 쓴다면 터미널의 가상환경과 선택된 인터프리터가 같은지 확인합니다.

VSCode에서 설치는 됐는데 import 오류가 계속 난다면 패키지 문제가 아니라 인터프리터 선택 문제일 수 있습니다.

공식 자료로 더 확인하기

requirements.txt 문법이나 가상환경 기준은 블로그 글보다 공식 문서를 함께 확인하는 것이 안전합니다. 특히 배포용 프로젝트나 팀 프로젝트에서는 현재 사용하는 pip, Python, uv 버전에 맞춰 문서를 확인하는 것이 좋습니다.

• pip 공식 문서에서 requirements.txt 파일 형식 확인하기
• Python 공식 문서에서 venv 가상환경 기준 확인하기
• uv 공식 문서에서 requirements.txt 설치 명령 확인하기

함께 보면 좋은 글

자주 묻는 질문

requirements.txt 설치 오류는 패키지 이름보다 Python 버전, 가상환경, 의존성 충돌, OS 빌드 도구를 순서대로 좁혀 가는 것이 핵심입니다.