Python 개발 환경 복구: 버전·의존성·설정 분리
새 환경에서 재현 가능한 설치와 CI 진단 순서를 정리하는 실행 안내입니다.
프로젝트가 기존 노트북에서만 실행된다면 설치 절차 중 일부가 사람의 기억에 남아 있을 수 있습니다. 개발 환경 복구는 패키지 설치뿐 아니라 Python 버전, 설정값, 데이터 준비와 실행 확인까지 포함해야 합니다.
새 환경에서 시작하는 순서
아래는 저장소 루트에서 실행하는 기본 예제입니다. 실제 프로젝트가 요구하는 Python 버전을 먼저 확인합니다.
python3 --version
python3 -m venv .venv
.venv/bin/python -m pip install -r requirements.txt
.venv/bin/python -m pip check
Windows에서는 가상환경 실행 파일 경로가 다릅니다. 이미 활성화된 환경이 무엇인지 불명확하면 python이라는 이름만 믿지 말고 실행 파일 경로를 확인합니다. 서로 다른 환경의 pip와 Python을 섞지 않는 것이 중요합니다.
코드 밖의 준비물 기록하기
| 준비물 | 저장할 곳 | 넣지 않을 것 |
|---|---|---|
| 런타임 버전 | README·버전 설정 파일 | 기억에만 의존한 조건 |
| 패키지 버전 | 의존성 파일·잠금 파일 | 현재 환경의 불필요한 전체 패키지 |
| 환경변수 이름 | 예시 설정 파일 | 실제 비밀키 |
| 샘플 데이터 | 재현 가능한 초기화 절차 | 운영 개인정보 복사본 |
예시 설정 파일에는 값의 형식과 필수 여부를 적습니다. 개발 DB 생성과 테스트 데이터 준비를 구분하고 운영 주소를 기본값으로 넣지 않습니다.
CI에서만 느리거나 실패할 때
의존성 다운로드, 빌드, DB 준비, 테스트를 단계별로 나눠 시간을 기록합니다. 전체 실행시간만 보면 캐시 미적중인지 느린 테스트인지 구분하기 어렵습니다. 캐시 키에는 의존성 파일과 런타임 차이를 반영해야 오래된 환경을 재사용하는 문제를 줄일 수 있습니다.
병렬 테스트를 도입하기 전에는 DB 이름, 임시 파일 경로, 포트가 충돌하지 않는지 확인합니다. 무작정 병렬 수를 늘리면 제한된 CPU와 메모리 때문에 오히려 느려질 수 있습니다.
복구 완료를 확인하는 기준
패키지 설치 성공 이후 최소 실행, 핵심 테스트, 문서의 예제 명령까지 확인합니다. 새 환경에서만 필요한 수동 단계가 발견되면 즉시 문서에 추가합니다. 의존성 최신화는 환경 복구와 다른 변경이므로 업데이트 절차로 분리하면 실패 원인을 찾기 쉽습니다.