Python Poetry에서 uv로 마이그레이션 완전 가이드: 패키지 관리 속도를 10배 높이는 실전 전환 방법

왜 uv로 갈아타야 할까?

Python 프로젝트를 관리하다 보면 pip install 하나 실행하는 데도 수십 초가 걸리는 경험, 한 번쯤 있으셨을 겁니다. Poetry는 의존성 관리를 우아하게 해결해 주지만, 속도 면에서는 아쉬운 점이 많았죠.

uv는 Rust로 작성된 차세대 Python 패키지 관리자로, Poetry 대비 10~100배 빠른 설치 속도를 자랑합니다.

이 글에서는 기존 Poetry 프로젝트를 uv로 안전하게 마이그레이션하는 전 과정을 단계별로 안내합니다.

Poetry vs uv: 무엇이 다를까?

Poetry의 설계 철학은 그대로 유지하면서, 실행 속도만 극대화한 것이 uv의 핵심 장점입니다.

1단계: uv 설치하기

macOS/Linux

curl -LsSf https://astral.sh/uv/install.sh | sh

Windows (PowerShell)

irm https://astral.sh/uv/install.ps1 | iex

설치 후 버전 확인:

uv --version
# 출력 예: uv 0.1.x

2단계: 기존 Poetry 프로젝트 분석

현재 프로젝트가 다음과 같은 구조라고 가정합니다:

my-project/
├── pyproject.toml
├── poetry.lock
└── src/
    └── app.py

pyproject.toml 예시

[tool.poetry]
name = "my-project"
version = "0.1.0"
description = ""
authors = ["Your Name <you@example.com>"]

[tool.poetry.dependencies]
python = "^3.9"
requests = "^2.31.0"
pandas = "^2.0.0"

[tool.poetry.dev-dependencies]
pytest = "^7.4.0"
black = "^23.0.0"

3단계: uv로 의존성 변환

uv는 Poetry의 pyproject.toml을 그대로 읽을 수 있습니다. 하지만 최적화를 위해 약간의 수정이 필요합니다.

변환 작업

1. 의존성 그룹 통합
   Poetry의 [tool.poetry.dev-dependencies]를 [project.optional-dependencies]로 변경:

[project]
name = "my-project"
version = "0.1.0"
requires-python = ">=3.9"
dependencies = [
    "requests>=2.31.0",
    "pandas>=2.0.0",
]

[project.optional-dependencies]
dev = [
    "pytest>=7.4.0",
    "black>=23.0.0",
]

2. poetry.lock 삭제
   uv는 자체 잠금 파일(uv.lock)을 생성하므로 기존 lock 파일은 제거:

rm poetry.lock

4단계: uv로 환경 초기화

가상환경 생성 + 패키지 설치

uv venv
source .venv/bin/activate  # Windows: .venv\Scripts\activate
uv pip install -r pyproject.toml

개발 의존성까지 설치:

uv pip install -e ".[dev]"

핵심 포인트: uv pip install은 기존 pip install과 거의 동일한 인터페이스를 제공하지만, 내부적으로 병렬 다운로드 + 캐싱으로 속도를 극대화합니다.

5단계: 속도 비교 실험

동일한 프로젝트에서 Poetry와 uv의 설치 시간을 측정해 봤습니다.

테스트 환경

• 프로젝트: pandas, numpy, scikit-learn 등 데이터 분석 패키지 50개
• 네트워크: 100Mbps

결과

특히 CI/CD 파이프라인에서 이 차이는 빌드 시간 단축으로 직결됩니다.

6단계: 스크립트 및 워크플로우 업데이트

Poetry 명령어를 uv로 변환:

GitHub Actions 예시

- name: Set up Python
  uses: actions/setup-python@v4
  with:
    python-version: '3.11'

- name: Install uv
  run: curl -LsSf https://astral.sh/uv/install.sh | sh

- name: Install dependencies
  run: |
    uv venv
    source .venv/bin/activate
    uv pip install -e ".[dev]"

7단계: 주의사항 및 트러블슈팅

1. 플러그인 호환성

Poetry 플러그인(예: poetry-dynamic-versioning)은 uv에서 작동하지 않습니다. 대안:
– setuptools_scm으로 버전 관리
– CI/CD에서 환경변수로 버전 주입

2. Private PyPI

비공개 패키지 저장소 사용 시 uv pip install에 --index-url 옵션 추가:

uv pip install --index-url https://pypi.mycompany.com/simple/ my-package

3. 잠금 파일 공유

팀원 간 환경 일치를 위해 requirements.txt 생성:

uv pip freeze > requirements.txt

실전 마이그레이션 체크리스트

• [ ] uv 설치 확인 (uv --version)
• [ ] pyproject.toml PEP 621 형식으로 변환
• [ ] poetry.lock 삭제
• [ ] uv venv로 가상환경 생성
• [ ] 의존성 설치 테스트 (uv pip install -e ".[dev]")
• [ ] 기존 테스트 스위트 실행 확인
• [ ] CI/CD 파이프라인 업데이트
• [ ] 팀원에게 마이그레이션 가이드 공유

마무리

Poetry에서 uv로의 마이그레이션은 기존 워크플로우를 거의 그대로 유지하면서도 속도를 극적으로 개선할 수 있는 현실적인 선택입니다.

핵심 요약:
– uv는 Rust 기반으로 10배 이상 빠른 패키지 설치 제공
– pyproject.toml 호환으로 마이그레이션 비용 최소화
– CI/CD 환경에서 빌드 시간 대폭 단축 가능
– Poetry 플러그인 의존성이 없다면 즉시 적용 가능

2024년 말 기준 uv는 아직 초기 단계이지만, Astral 팀(Ruff 개발사)의 적극적인 개발로 빠르게 성숙하고 있습니다. 속도가 중요한 프로젝트라면 지금 바로 시도해 볼 가치가 충분합니다.