라떼군 이야기
Python uv 패키지 매니저에서 requirements.txt로 의존성 일괄 설치하기
Problem
Rust로 작성된 고성능 Python 패키지 매니저인 uv를 처음 도입하여 사용할 때 흔히 겪는 문제입니다. 기존 프로젝트에 존재하는 requirements.txt 파일이 있을 때, 여기에 나열된 수많은 패키지들을 uv 환경에 어떻게 설치해야 할지 막막할 수 있습니다. uv pip install 패키지명 명령어로 하나씩 수동 설치하는 것은 패키지 수가 많을 경우 매우 비효율적이고 번거로운 작업이 됩니다.
Background
uv는 pip, pip-tools, virtualenv를 대체하기 위해 만들어진 매우 빠른 Python 패키지 설치 도구입니다. 기존의 pip 사용자는 pip install -r requirements.txt 명령어에 익숙하지만, uv는 독자적인 명령어 체계를 가지고 있어 혼동이 올 수 있습니다. uv는 단순히 패키지를 설치하는 기능(pip 인터페이스)뿐만 아니라, pyproject.toml을 기반으로 프로젝트 전체의 의존성을 관리하는 기능(Project 인터페이스)도 함께 제공하므로 상황에 맞는 명령어를 선택하는 것이 중요합니다.
Solution
uv를 사용하여 requirements.txt 파일의 내용을 설치하는 방법은 크게 두 가지가 있습니다. 사용 목적에 따라 적절한 방법을 선택하세요.
방법 1: 단순 가상 환경 설치 (Legacy 방식)
단순히 현재 활성화된 가상 환경(venv)에 패키지를 설치하고 싶다면 uv pip 인터페이스를 사용합니다. 이는 기존 pip install -r 명령어와 가장 유사하게 동작합니다.
# requirements.txt에 명시된 모든 패키지를 현재 가상 환경에 설치합니다.
# 기존 pip보다 훨씬 빠른 속도로 설치가 진행됩니다.
uv pip install -r requirements.txt
방법 2: 프로젝트 의존성으로 추가 (Modern 방식)
만약 uv로 관리되는 프로젝트(Application 또는 Library)를 작업 중이라면, uv add 명령어를 사용하는 것이 권장됩니다. 이 명령어는 패키지를 설치함과 동시에 프로젝트의 설정 파일인 pyproject.toml에도 의존성 정보를 자동으로 업데이트합니다.
# requirements.txt의 패키지들을 설치하고,
# 동시에 pyproject.toml 파일의 dependencies 섹션에 추가합니다.
uv add -r requirements.txt
주요 차이점:
uv pip install: 단순히 환경에 패키지만 설치합니다 (일회성 혹은 레거시 호환용).uv add: 패키지를 설치하고 프로젝트 메타데이터(pyproject.toml)를 관리하여 재현 가능한 환경을 만듭니다.
Deep Dive
uv add -r requirements.txt 명령어는 기존 레거시 프로젝트를 현대적인 pyproject.toml 기반 프로젝트로 마이그레이션할 때 매우 유용합니다. 이 명령어를 실행하면 uv는 requirements.txt를 파싱하여 최신 버전 제약 조건을 pyproject.toml에 기록하고, 정확한 잠금 파일인 uv.lock을 생성합니다. 이를 통해 팀원 간에 완벽하게 동일한 패키지 버전을 보장할 수 있으며, CI/CD 파이프라인에서의 안정성도 크게 향상됩니다.
Conclusion
uv 환경에서 requirements.txt를 설치할 때는 상황에 따라 명령어를 선택해야 합니다. 단순 설치가 목적이라면 uv pip install -r requirements.txt를, 프로젝트 관리 및 pyproject.toml로의 전환이 목적이라면 uv add -r requirements.txt를 사용하세요. uv의 강력한 성능을 통해 의존성 설치 시간을 획기적으로 단축할 수 있습니다.