파이썬 requirements.txt는 현재 선택한 환경에 설치된 패키지를 기록한 뒤 새 가상환경에 다시 설치하는 출발점입니다. 다만 pip freeze는 현재 상태를 저장할 뿐 프로젝트에 꼭 필요한 의존성만 골라 주지는 않으므로, 먼저 어떤 Python과 pip를 사용 중인지 확인하고 설치 후 pip check와 실제 코드 검증까지 이어가야 합니다.
먼저 확인할 것: Python과 pip가 같은 환경인가
pip만 단독으로 호출하면 다른 Python에 연결된 pip를 사용할 수 있습니다. 운영에서는 대상 인터프리터를 명시하는 python -m pip 형태를 기본으로 두고, 다음 명령으로 현재 위치를 확인합니다.
python --version
python -m pip --version
가상환경을 쓰고 있다면 python -m pip --version의 경로가 프로젝트의 가상환경 아래를 가리키는지 봅니다. 공식 Python Packaging 가이드도 활성화된 환경에서 which python 또는 Windows의 where python으로 인터프리터 경로를 확인하고, python -m pip --version으로 연결된 Python과 설치 경로를 확인하는 방식을 안내합니다.
아직 가상환경을 만들지 않았다면 프로젝트 디렉터리에서 다음처럼 만들고 활성화합니다.
python -m venv .venv
# macOS·Linux
source .venv/bin/activate
# Windows PowerShell
.venv\Scripts\Activate.ps1
가상환경은 프로젝트별 Python과 패키지 설치 위치를 분리합니다. 따라서 전역 환경에서 이미 많은 패키지를 설치한 상태라면, 그 목록을 곧바로 프로젝트의 의존성 목록으로 간주하지 않는 편이 안전합니다.
현재 가상환경에서 requirements.txt 만들기
환경을 확인했다면 다음 명령으로 설치된 패키지를 requirements 형식으로 출력합니다.
python -m pip freeze > requirements.txt
pip freeze는 설치된 배포 패키지를 requirements 형식으로 보여 주는 명령입니다. 가상환경에서 실행하면 그 환경의 상태를 기록하는 데 적합합니다. 다만 이것은 의존성 solver가 계산한 결과나 lockfile을 새로 만드는 명령은 아닙니다. 현재 환경에 무엇이 설치되어 있는지를 스냅샷으로 남기는 작업에 가깝습니다.
목록이 비어 있다면 곧바로 명령 실패로 판단하지 말고 다음을 확인합니다.
- 가상환경을 실제로 활성화했는지
python -m pip --version이 예상한.venv경로를 가리키는지- 패키지를 다른 Python이나 전역 환경에 설치한 것은 아닌지
반대로 목록이 프로젝트 규모에 비해 지나치게 크다면 전역 패키지가 섞였거나, 현재 환경을 여러 작업이 함께 사용했을 가능성을 먼저 살핍니다. 가상환경에서 전역 패키지를 함께 보도록 설정한 경우에는 --local 옵션으로 해당 환경에 로컬로 설치된 패키지만 출력하는 선택지도 있습니다.
python -m pip freeze --local > requirements.txt
이때도 파일을 무조건 줄이는 것보다, 애플리케이션이 실제로 필요로 하는 패키지와 개발·검증 도구를 구분했는지 확인하는 것이 중요합니다. 목록에서 직접 쓰지 않는 패키지를 임의로 삭제하면 새 환경에서 누락을 발견하는 시점이 늦어질 수 있습니다.
새 가상환경에서 설치하기
재현 여부를 확인하려면 원래 환경을 그대로 사용하지 말고 새 위치에 가상환경을 만든 뒤 파일을 설치합니다.
python -m venv .venv-repro
# macOS·Linux
source .venv-repro/bin/activate
# Windows PowerShell
.venv-repro\Scripts\Activate.ps1
python -m pip install -r requirements.txt
설치 명령이 성공했다는 사실은 패키지 설치 과정이 끝났다는 뜻입니다. 애플리케이션이 정상 동작한다는 뜻까지 포함하지는 않습니다. 특히 원래 환경과 새 환경의 Python 버전, 운영체제, 플랫폼별 바이너리 조건이 다르면 같은 파일로 완전히 동일한 환경이 보장되지 않을 수 있습니다.
설치 뒤에는 의존성과 실제 코드를 따로 검증하기
첫 번째 검사는 설치된 패키지 사이의 요구 조건입니다.
python -m pip check
문제가 없으면 No broken requirements found가 출력되고 종료 코드 0을 반환합니다. 누락된 패키지나 요구 버전 불일치가 있으면 오류가 출력되고 종료 코드 1을 반환하므로, 자동화에서는 이 결과를 실패 조건으로 연결할 수 있습니다.
두 번째 검사는 프로젝트가 실제로 import되고 핵심 경로가 실행되는지입니다. 예를 들어 애플리케이션에 별도의 점검 명령이나 테스트가 있다면 새 환경에서 실행합니다.
python -c "import your_package; print('import ok')"
python -m pytest
위 예시는 프로젝트가 your_package와 pytest를 실제로 사용하는 경우에 적용하는 형태입니다. 프로젝트에 맞는 모듈명과 테스트 명령으로 바꿔야 하며, 실행하지 않은 결과를 성공한 것처럼 기록해서는 안 됩니다. pip check가 통과해도 애플리케이션의 import 경로, 설정값, 외부 서비스 연결, 테스트 로직까지 대신 확인해 주지는 않습니다.
requirements.txt를 어디까지 믿을 것인가
이 파일은 한 환경의 설치 상태를 다른 환경에서 재현해 보는 실용적인 출발점입니다. 하지만 다음 범위까지 자동으로 해결한다고 보면 안 됩니다.
- 프로젝트가 실제로 사용하는 패키지와 현재 환경에 우연히 남은 패키지의 구분
- Python 버전이나 운영체제가 달라졌을 때의 호환성
- 환경변수, 외부 서비스, 운영체제 도구 같은 패키지 밖의 조건
- 애플리케이션의 import와 테스트 성공 여부
따라서 판단 순서는 간단하게 잡을 수 있습니다. 먼저 python -m pip --version으로 대상 환경을 확인하고, 그 환경에서 freeze를 실행합니다. 새 가상환경에서는 install -r 뒤에 pip check, 실제 import, 프로젝트 테스트 순서로 확인합니다. 이 과정을 통과했다면 해당 requirements.txt를 현재 프로젝트의 재현 절차에 포함할지 판단할 수 있습니다.
requirements.txt와 pyproject.toml의 역할을 나누는 문제, 로컬 경로나 비공개 저장소 주소가 목록에 들어갔는지 확인하는 문제, 새 Python 버전이나 다른 운영체제에서 설치가 실패하는 문제는 각각 별도의 의사결정이 필요한 주제입니다. 여기서는 pip freeze로 만든 파일을 올바른 환경에서 만들고 검증하는 범위에 집중했습니다.