[PYTHON] 프로젝트 협업을 위한 requirements.txt 생성 방법과 환경 충돌 해결을 위한 3가지 활용팁

requirements.txt 생성 방법

 

파이썬 프로젝트를 진행하다 보면 다양한 외부 라이브러리를 사용하게 됩니다. 하지만 내가 개발한 코드를 다른 환경(동료의 컴퓨터, 서버 등)에서 실행할 때 패키지 버전이 맞지 않아 오류가 발생하는 경우가 빈번합니다. 이러한 문제를 예방하고 프로젝트의 재현성(Reproducibility)을 보장하기 위한 표준 해결책이 바로 requirements.txt 파일입니다. 본 글에서는 이 파일의 생성부터 관리, 그리고 실무에서 발생하는 충돌 해결 방법의 차이를 상세히 다룹니다.

---

1. requirements.txt의 정의와 필수적인 이유

requirements.txt는 파이썬 프로젝트가 의존하고 있는 패키지 목록과 각 패키지의 특정 버전을 명시한 텍스트 파일입니다. 이 파일이 중요한 이유는 다음과 같습니다.

• 환경 일관성 유지: 개발, 테스트, 운영 환경 간의 라이브러리 버전을 동일하게 맞춥니다.
• 자동화된 배포: CI/CD 파이프라인이나 클라우드 서비스(AWS, GCP 등)에서 자동으로 환경을 구축할 수 있게 합니다.
• 용량 최적화: 수 기가바이트에 달하는 패키지 폴더(site-packages)를 직접 공유하는 대신, 몇 킬로바이트의 텍스트 파일 하나로 모든 의존성을 관리합니다.

---

2. 파일 생성 및 설치를 위한 핵심 명령어와 활용 방법

파이썬 개발자라면 반드시 숙지해야 할 requirements.txt의 기본적인 3가지 사용법입니다.

1단계: 현재 환경의 패키지 목록 추출

터미널이나 명령 프롬프트에서 다음 명령어를 입력하면 현재 설치된 모든 패키지와 버전 정보가 파일로 저장됩니다.

pip freeze > requirements.txt

2단계: 파일 내용을 바탕으로 환경 구축

새로운 환경에서 프로젝트를 시작할 때, 일일이 패키지를 설치할 필요 없이 아래 명령어로 한 번에 해결합니다.

pip install -r requirements.txt

3단계: 특정 조건 부여 (고급 활용)

단순히 버전 고정뿐만 아니라, 특정 버전 이상을 요구하거나 제외하는 규칙을 파일 내에 작성할 수 있습니다.

requests>=2.25.1
pandas<2.0.0
numpy==1.21.0

---

3. 환경 관리 도구별 의존성 관리 방식의 차이 비교

프로젝트 규모와 목적에 따라 requirements.txt를 사용하는 방식과 대체 도구들 간에는 명확한 차이가 존재합니다.

구분	Standard pip (txt 방식)	Pipenv (Lock 방식)	Poetry (Toml 방식)
생성 방법	명령어 수동 입력 (pip freeze)	패키지 설치 시 자동 갱신	프로젝트 설정 시 자동 관리
의존성 해결	충돌 발생 시 수동 해결 필요	하위 의존성까지 그래프 관리	강력한 결정적 빌드 지원
파일 가독성	단순 리스트 (매우 높음)	JSON 형태 (중간)	TOML 형태 (높음)
표준성	파이썬 표준 (가장 범용적)	워크플로우 중심 도구	차세대 패키징 표준 지향

---

4. [Sample Example] 실무 환경에서의 트러블슈팅 사례

로컬 환경에서 잘 작동하던 코드가 서버에서 에러를 낼 때, requirements.txt를 활용해 해결하는 전형적인 시나리오입니다.

문제 상황: 로컬은 Pandas 2.x, 서버는 Pandas 1.x로 인한 에러

# [해결 방법]
# 1. 로컬에서 가상환경(venv)을 활성화한다.
# 2. 프로젝트에 필요한 최소한의 패키지만 설치한다.
pip install pandas==2.0.3 requests

# 3. 환경을 캡슐화하여 파일로 뽑아낸다.
pip freeze > requirements.txt

# 4. 서버로 requirements.txt를 전송 후 실행한다.
pip install -r requirements.txt
    

전문가 팁: pip freeze는 현재 환경의 모든 패키지를 가져오므로, 반드시 가상환경(venv)을 먼저 생성하고 프로젝트 필수 패키지만 설치한 뒤 파일을 만드는 것이 깔끔한 관리의 비결입니다.

---

5. 결론: 지속 가능한 개발을 위한 첫걸음

requirements.txt를 철저히 관리하는 습관은 팀 프로젝트에서 발생할 수 있는 '내 컴퓨터에서는 되는데?'라는 고질적인 문제를 근본적으로 해결해 줍니다. 단순한 텍스트 파일이지만, 그 안에는 프로젝트의 생명주기를 관통하는 중요한 정보가 담겨 있습니다. 오늘부터 여러분의 깃허브(GitHub) 레포지토리에 이 파일을 포함시켜 보세요.

---

[내용 출처 및 참고 문헌]

• Python.org. "Installing Packages using pip and virtual environments."
• PyPA (Python Packaging Authority). "Requirements Files Reference."
• Two Scoops of Django (Greenfeld & Greenfeld). "Chapter 25: Best Practices for pip and requirements files."