Python uv 환경에서 requirements.txt 최신 버전으로 업데이트하는 방법
Problem
로컬 개발 환경에서는 Python 패키지 매니저로 uv를 사용하지만, 프로덕션이나 배포 환경에서는 여전히 pip를 사용하는 경우가 많습니다. 이때 uv lock --upgrade 명령어를 통해 패키지를 최신 버전으로 업데이트하고 uv.lock 파일을 갱신한 뒤, 이를 requirements.txt로 추출해야 합니다. 하지만 많은 개발자들이 uv pip compile pyproject.toml --output-file requirements.txt 명령어를 사용했다가, requirements.txt 파일에 최신 버전이 반영되지 않고 이전 버전이 그대로 남아있는 문제를 겪곤 합니다.
Background
uv는 Rust로 작성된 매우 빠른 Python 패키지 및 프로젝트 관리 도구입니다. 최신 Python 프로젝트들은 pyproject.toml로 의존성을 선언하고, uv.lock과 같은 잠금 파일(Lock file)을 통해 정확한 패키지 버전을 고정합니다. uv pip compile 명령어는 주로 requirements.in이나 pyproject.toml을 읽어 의존성을 해결(resolve)하는 역할을 하지만, 이미 업데이트된 uv.lock 파일의 상태를 직접적으로 requirements.txt 포맷으로 변환하는 데는 적합하지 않을 수 있습니다. 따라서 잠금 파일에 명시된 최신 버전을 정확히 추출하기 위해서는 uv에서 제공하는 전용 내보내기(Export) 기능이나 환경 고정(Freeze) 기능을 사용해야 합니다.
Solution
이 문제를 해결하고 최신 버전이 반영된 requirements.txt를 생성하는 방법에는 크게 두 가지가 있습니다.
방법 1: uv export 명령어 사용 (권장)
가장 명시적이고 권장되는 방법은 uv export 명령어를 사용하는 것입니다. 이 명령어는 uv.lock 파일을 읽어 지정한 포맷으로 의존성을 내보냅니다.
# 해시(hash) 값을 제외하고 requirements.txt 형식으로 내보내기
uv export --no-hashes --format requirements-txt > requirements.txt
--no-hashes: 패키지의 무결성 검증을 위한 해시 값을 출력에서 제외합니다. 보안상 해시 검증이 필요한 프로덕션 환경이라면 이 옵션을 제거하여 해시를 포함시킬 수 있습니다.--format requirements-txt: 출력 형식을requirements.txt호환 포맷으로 지정합니다.
방법 2: uv pip freeze 명령어 사용
기존 pip 사용자에게 익숙한 방식인 freeze를 사용할 수도 있습니다. 이 방법은 현재 활성화된 가상 환경에 실제로 설치된 패키지 목록을 출력합니다.
# 현재 환경에 설치된 패키지 목록을 requirements.txt로 저장
uv pip freeze > requirements.txt
- 이 명령어를 사용하기 전에는 반드시
uv sync등을 통해 로컬 가상 환경에 최신 패키지가 실제로 설치되어 있어야 정확한 결과를 얻을 수 있습니다.
Deep Dive
uv export와 uv pip freeze는 결과물이 비슷해 보이지만 동작 방식에 중요한 차이가 있습니다. uv export는 로컬 가상 환경의 상태와 무관하게 오직 uv.lock 파일만을 기준으로 작동합니다. 따라서 패키지를 실제로 설치하지 않은 상태의 CI/CD 파이프라인에서도 빠르고 일관되게 requirements.txt를 생성할 수 있습니다. 반면 freeze는 현재 환경에 설치된 패키지를 기준으로 하므로, 개발 과정에서 테스트용으로 임시 설치한 패키지가 프로덕션 배포 파일에 섞여 들어갈 위험이 있습니다. 따라서 프로덕션 배포용 파일을 생성할 때는 항상 락 파일을 기반으로 하는 uv export를 사용하는 것이 베스트 프랙티스입니다.
Conclusion
uv로 관리되는 프로젝트에서 requirements.txt를 최신 상태로 업데이트하려면 uv pip compile 대신 uv export 명령어를 사용하는 것이 좋습니다. 이를 통해 uv.lock에 반영된 최신 패키지 버전들을 누락 없이 안전하고 일관되게 프로덕션 환경으로 전달할 수 있습니다.