[PYTHON] requirements.txt 파일을 만드는 5가지 전문 방법과 의존성 충돌 해결 가이드

requirements.txt 파일

파이썬 프로젝트를 진행하다 보면 수많은 외부 라이브러리를 사용하게 됩니다. 하지만 개발 환경에서 잘 작동하던 코드가 다른 팀원의 PC나 클라우드 서버에서 "ModuleNotFoundError"를 뿜어내며 멈추는 일은 흔합니다. 이를 방지하는 가장 핵심적인 도구가 바로 requirements.txt입니다. 단순히 패키지 목록을 나열하는 것을 넘어, 파이썬 생태계의 복잡한 의존성 구조를 이해하고 버전 충돌을 해결하는 전문적인 생성 방법을 아는 것은 시니어 개발자의 필수 역량입니다. 본 포스팅에서는 2026년 실무 표준에 부합하는 5가지 생성 기법과 7가지 실전 해결 사례를 심도 있게 다룹니다.

---

1. requirements.txt 생성 도구별 특성 및 결정적 차이

많은 초보자가 pip freeze 하나만을 사용하지만, 실무에서는 프로젝트의 순수성을 유지하기 위해 다양한 도구를 상황에 맞춰 선택해야 합니다. 각 방식의 장단점을 아래 표로 정리하였습니다.

생성 도구 / 방법	주요 특징	의존성 해결 능력	권장 상황
pip freeze	현재 환경의 모든 패키지 출력	낮음 (환경 전체 스냅샷)	단순 가상환경 백업
pipreqs	import 문을 분석하여 필요한 것만 추출	높음 (최소 패키지 구성)	지저분한 환경에서 프로젝트 분리 시
pip-compile (pip-tools)	느슨한 정의로부터 엄격한 버전 고정	매우 높음 (의존성 그래프 최적화)	대규모 협업 및 운영 배포
Poetry export	Poetry 설정 파일을 txt로 변환	최상 (해시 검증 포함)	최신 모던 파이썬 프로젝트
Conda list -e	아나콘다 전용 패키지 포맷 추출	중간 (C-extension 포함)	데이터 과학 및 AI 연구 환경

2. 왜 버전 고정(Pinning)이 해결의 핵심인가?

파이썬 패키지들은 서로 거미줄처럼 얽혀 있습니다. 예를 들어 Library A가 Library B v1.0을 요구하는데, 당신이 Library B v2.0을 설치하면 Library A는 작동을 멈춥니다. requirements.txt에 == 연산자를 사용하여 버전을 명시하는 것은 단순히 선택이 아니라, 소프트웨어의 재현성(Reproducibility)을 확보하기 위한 최후의 방어선입니다.

---

3. 실무 효율을 극대화하는 requirements.txt 생성 및 해결 사례 7가지 (Examples)

단순한 파일 생성을 넘어, 개발 현장에서 즉시 적용하여 문제를 해결할 수 있는 고급 예제들입니다.

Example 1: 가상환경의 순수성을 보존하는 pip freeze 활용

가장 표준적인 방법으로, venv 환경을 활성화한 상태에서 실행합니다.

# 가상환경 활성화 후 실행
# 현재 설치된 모든 패키지와 버전을 파일로 저장
pip freeze > requirements.txt

# 생성된 내용 확인
# Django==4.2.1
# requests==2.31.0
        

Example 2: 지저분한 전역 환경에서 필요한 것만 골라내기 (pipreqs)

가상환경 없이 개발하다가 프로젝트에 실제 사용된 패키지만 추출해야 할 때 유용한 해결 방법입니다.

# pipreqs 설치
pip install pipreqs

# 현재 디렉토리 스캔하여 필요한 패키지만 생성
# --force 옵션은 기존 파일을 덮어쓰기 위해 사용
pipreqs . --encoding=utf8 --force

# 결과: 코드 내 'import'된 패키지만 포함되어 매우 깔끔함
        

Example 3: 개발용과 운영용 의존성 분리 해결 (Layered Requirements)

테스트 도구(pytest)는 운영 서버에 필요 없습니다. 이를 계층적으로 관리하여 서버 부하를 줄입니다.

# base.txt (공통 패키지)
requests==2.31.0

# dev.txt (개발용 - base 포함)
-r base.txt
pytest==7.4.0
black==23.7.0

# 서버에서는 pip install -r base.txt만 실행하여 해결
        

Example 4: 보안 강화를 위한 해시값 포함 생성 (pip-compile)

패키지 위변조를 방지하기 위해 각 패키지의 고유 해시값을 포함하는 방법입니다.

# pip-tools 설치
pip install pip-tools

# requirements.in 파일 생성 (필요한 패키지 이름만 작성)
# echo "requests" > requirements.in

# 해시값을 포함한 엄격한 txt 파일 생성
pip-compile --generate-hashes requirements.in

# 결과: 각 버전의 SHA256 해시가 포함되어 보안성 극대화
        

Example 5: 특정 플랫폼(M1 Mac vs Windows) 간 차이 해결

OS마다 다른 바이너리를 요구하는 패키지가 있을 때 조건부 의존성을 명시합니다.

# requirements.txt 내부에 마커(Markers) 사용
pywin32==306; sys_platform == 'win32'
appnope==0.1.3; sys_platform == 'darwin'

# 이렇게 작성하면 pip가 실행 환경을 판단하여 알맞은 것만 설치함
        

Example 6: 비공개 GitHub 저장소 패키지 포함 방법

PyPI에 등록되지 않은 사내 프라이빗 저장소의 라이브러리를 의존성에 추가하는 해결책입니다.

# git+ssh 또는 git+https 프로토콜 사용
# 특정 브랜치나 태그 지정 가능
git+https://github.com/company/private-lib.git@v1.0.2#egg=private-lib

# 설치 시: pip install -r requirements.txt
        

Example 7: 의존성 충돌 발생 시 원인 분석 및 강제 해결

패키지 간 버전 요구사항이 충돌하여 설치가 안 될 때의 디버깅 전략입니다.

# pip의 최신 의존성 해결사(20.3+)를 활용한 충돌 확인
pip install -r requirements.txt --use-feature=2020-resolver

# 충돌이 발생한 패키지 간의 관계 확인
pip show [패키지명]

# 임시 해결: --no-deps 옵션으로 의존성 무시 설치 (주의 필요)
# pip install [패키지명] --no-deps
        

---

4. 결론: 지속 가능한 개발 환경을 위한 제언

requirements.txt를 관리하는 것은 단순히 파일을 저장하는 행위가 아니라, 프로젝트의 생명력을 유지하는 행위입니다. 2026년의 개발 환경은 더 복잡해지고 있으며, 수동으로 패키지 버전을 관리하는 시대는 지났습니다. 가장 추천하는 해결 방법은 venv나 conda로 환경을 엄격히 격리한 뒤, pip-tools나 Poetry를 사용하여 의존성 그래프를 자동으로 관리하는 것입니다. 이를 통해 "어제까지는 됐는데 오늘은 왜 안 되지?"라는 고질적인 문제를 해결하고, 더 본질적인 코드 로직 구현에 집중할 수 있는 환경을 구축하시길 바랍니다.

5. 내용의 출처 및 참고 문헌

• Python Packaging User Guide: Requirements Files (Official)
• PyPA GitHub: pip-tools: A set of command line tools to keep your pinned dependencies fresh
• Real Python: Effective Python Project Management
• Stack Overflow: Managing Python dependencies in 2026 environment