requirements.txt 사용법: 실무에서 바로 쓰는 가이드

requirements.txt 사용법이 필요한 상황

requirements.txt 사용법은 프로젝트의 Python 패키지 의존성을 명확히 기록하고 재현 가능한 개발·배포 환경을 만들기 위해 필요합니다. 이 문서에서는 생성 방법, 버전 고정 전략, 분리 및 배포 적용 방법과 함께 보안·운영 주의점, 실무 체크리스트를 제공해 실제로 바로 적용할 수 있게 설명합니다.

requirements.txt 사용법 핵심 개념

requirements.txt는 pip 기반의 의존성 목록 파일로, 각 줄에 패키지==버전 형식으로 작성하는 것이 일반적입니다. 핵심 개념은 다음과 같습니다.

• 재현성: 정확한 버전을 기록해 동일한 환경을 재현합니다.
• 계층화: 개발용/프로덕션용 의존성을 분리합니다.
• 관리 방법: 수동 편집, pip freeze, pip-tools(compile/sync) 등을 활용합니다.

requirements.txt 사용법 실무 예제

아래 예제는 가상환경을 만들고 requirements.txt를 생성·사용하는 기본 흐름입니다.

# 가상환경 생성
python -m venv .venv
source .venv/bin/activate  # macOS/Linux
.\.venv\Scripts\activate   # Windows

# 패키지 설치
pip install requests flask

# 현재 환경을 requirements.txt로 저장
pip freeze > requirements.txt

# 다른 환경에서 설치
pip install -r requirements.txt

파이썬 코드 예제(간단한 requirements 파일 로드 확인 스크립트):

# requirements_checker.py
with open('requirements.txt') as f:
    pkgs = [line.strip() for line in f if line.strip() and not line.startswith('#')]
for p in pkgs:
    print(p)

requirements 파일 분리와 관리 전략

실무에서는 개발·테스트·프로덕션 의존성을 분리합니다. 예:

• requirements.txt: 프로덕션 필수 패키지
• dev-requirements.txt: 개발 도구(테스트, 포매터 등)
• constraints.txt: 패키지 업스트림 충돌을 제어

예시 명령:

pip freeze > requirements.txt
pip freeze > dev-requirements.txt
# 또는 pip-tools 사용
pip-compile requirements.in
pip-sync

비교: 버전 고정 전략 판단 기준

위 표를 기반으로 팀 정책을 정해 일관성 있게 적용하세요.

언제 쓰면 좋고 언제 피해야 할까

• 언제 쓰면 좋은가

  • 동일한 실행 환경을 여러 개발자/CI에 재현해야 할 때
  • 배포 파이프라인에서 설치 단계가 필요할 때
  • 버전 충돌을 명시적으로 관리해야 할 때

• 언제 피해야 하는가

  • 매우 복잡한 종속성 그래프를 가진 대형 프로젝트에서 단일 파일로 관리하기 어려울 때(이 경우 poetry, pipenv, conda 고려)
  • 패키지가 빠르게 바뀌며 최신 버전을 항상 사용해야 하는 실험적 프로젝트

실무 체크리스트

• 가상환경을 사용하고 있는가?
• requirements 파일이 git에 커밋되어 있는가?(비밀키 포함 여부 확인)
• 개발용/프로덕션용 의존성이 분리되어 있는가?
• CI에서 동일한 파일로 설치 테스트를 하고 있는가?
• 패키지 소스(인덱스)를 명시적으로 지정하고 있는가?(사설 레포지토리 사용시)

성능·보안·운영 주의점

• 보안
  • requirements.txt에 비밀 정보(토큰, URL에 포함된 자격증명)를 넣지 마세요.
  • 공개된 패키지 취약점은 Dependabot, GitHub Alerts 등으로 모니터링하세요.
• 성능
  • 불필요한 대형 패키지는 제외하고 최소 집합만 기록하세요. 빌드 시간이 줄어듭니다.
  • 병렬 설치가 가능한 환경(CI 캐시 활용)에서 pip의 캐시와 wheel을 사용하세요.
• 운영
  • 프로덕션 배포 시 사내 패키지 인덱스(예: Artifactory)를 사용하면 외부 장애를 줄일 수 있습니다.
  • constraints 파일로 하위 의존성의 버전을 통제해 예측 가능한 배포를 유지하세요.

자주 묻는 질문

Q1: requirements.txt와 Pipfile/poetry 중 무엇을 선택해야 하나요? A1: 단순한 프로젝트나 기존 파이프라인과 호환성이 필요하면 requirements.txt가 적합합니다. 의존성 해석, 락 파일 자동화, 가상 환경 관리가 필요하면 poetry를 고려하세요.

Q2: pip freeze로 생성된 파일을 바로 커밋해도 되나요? A2: 개발 중에는 가능하지만, 프로덕션용으로는 불필요한 개발 의존성이 포함될 수 있으니 파일을 분리하거나 필터링 후 커밋하세요.

Q3: requirements.txt에서 특정 패키지의 하위 의존성까지 고정해야 하나요? A3: 재현성이 중요하면 하위 의존성까지 고정하는 것이 안전합니다. pip-tools나 poetry의 lock 기능을 사용해 관리하세요.

Q4: private package index를 requirements에 어떻게 명시하나요? A4: --extra-index-url 또는 --index-url을 사용해 pip install 시 지정하거나, pip.conf/requirements 파일 주석으로 관리하세요. 자격증명은 환경변수/CI 시크릿으로 관리하세요.

정리

• requirements.txt 사용법은 재현 가능한 환경을 만드는 기본 도구입니다.
• 개발/프로덕션 의존성 분리와 버전 전략을 팀 규칙으로 정하세요.
• 보안(비밀정보), 성능(불필요 패키지), 운영(사내 레포지토리, constraints) 주의하세요.
• 실무 체크리스트를 CI에 통합해 자동화하세요。
• 필요 시 pip-tools, poetry 같은 도구를 병행 검토하세요。