uv migration

Poetry $\to$ uv 마이그레이션으로 얻은 것들

더 빠르게, 더 가볍게, 더 안전하게

현재 운영 중인 woorinara-chatbot 프로젝트는 Python 패키지 매니저로 Poetry를 사용 중이다. 물론 큰 문제 없이 돌아가고 있지만, 최근 uv의 설치 속도를 경험하고 나니 굳이 Poetry를 고집할 이유가 없다는 생각이 들었다. 결국 Poetry $\to$ uv로 마이그레이션을 직접 진행했고, 그 결과 빌드 시간, 이미지 용량, 배포 속도에서 눈에 띄는 개선이 있었다.

왜 uv인가?

기능	장점
Rust 기반	병렬 처리 + 압도적인 설치 속도
PEP 582 지원	.venv 없이 작동 가능 (프로젝트 내 패키지 관리)
Docker 친화적	슬림한 이미지 + 빠른 빌드 속도
Poetry lock 지원	기존 프로젝트 마이그레이션 부담 ↓

기존 Docker build 상황

poetry install 기반으로 Docker 빌드 시:

• Build Time: 322.6초
• Image Size: 2.6GB

docker build -t chatbot-api-test .
docker image ls
 
REPOSITORY         TAG       IMAGE ID       CREATED         SIZE
chatbot-api-test   latest    f70127f83f39   4 minutes ago   2.6GB

uv 도입 준비 과정

1. Python 버전 확인:

python --version # Python 3.12.0	

2. Poetry 가상환경 제거:

poetry env remove python
rmdir /S /Q .venv

3. 프로젝트 백업 및 브랜지 분리:

xcopy /E /I /H "woorinara-chatbot-api" "woorinara-chatbot-api-poetry-backup"
git checkout -b migrate/uv

4. uv 설치 및 초기화:

pip install uv
uv init  # pyproject.toml, uv.lock 생성
uv sync  # 가상환경 생성 및 패키지 설치

Dockerfile 최적화 (Poetry $\to$ uv)

FROM python:3.12-slim
WORKDIR /app
 
RUN pip install --no-cache-dir uv
 
COPY pyproject.toml uv.lock* ./
RUN uv sync --frozen --no-dev
 
COPY ./app ./app
COPY --from=public.ecr.aws/awsguru/aws-lambda-adapter:0.9.0 /lambda-adapter /opt/extensions/lambda-adapter
 
ENV PORT=8000
ENV PATH="/app/.venv/bin:$PATH"
 
HEALTHCHECK --interval=30s --timeout=30s --start-period=5s --retries=3 \
    CMD curl -f http://localhost:8000/health || exit 1
 
CMD ["uvicorn", "--host=0.0.0.0", "--port=8000", "app.main:app"]

마이그레이션 결과

• Build Time: 87.6초 (기존 대비 73% 감소)
• Image Size: 1.01GB (기존 대비 61% 감소)

체감 효과 요약

1. 배포 속도 단축
   • GitHub Actions, AWS CodeBuild 등에서 파이프라인 실행 시간 감소
   • DockerHub/ECR push/pull 속도 향상 $\to$ 배포 시간 절약
2. 비용 절감
   • CI 서버 시간 단축 $\to$ 빌드 비용 감소
   • Registry 저장소 사용량 감소
   • 전송 비용 절감 (특히 cross-region 배포 시)
3. 보안성 및 유지보수 효율 향상
   • --no-dev, --no-cache, slim 기반 $\to$ 공격 벡터 감소
   • 단일 기능 중심 이미지 $\to$ 문제 디버깅 및 롤백 용이
4. **Cold Start 감소 (Lambda, Cloud Run 등)

이미지 크기	Cold Start 평균 시간
2.6GB	3~5초 이상
1.0GB	1~2초 이내
<500MB	거의 실시간

5. 개발 반복 속도 개선
   • 로컬에서 Docker 빌드 및 테스트 속도 향상
   • 저장 공간 절약, 개발 생산성 향상

결론

Poetry도 훌륭한 패키지 매니저이지만, Docker 중심의 서비스 운영 환경에서는 uv가 보여주는 속도와 효율성이 압도적이다. 특히 빌드 시간이 줄고 이미지가 가벼워지면, 배포만 빨라지는 것이 아니라 전체 서비스 운영의 리듬이 가벼워진다. 시간을 투자해서 마이그레이션하면, 그 이후 수십 번의 배포가 더 빠르고 더 안정적으로 진행된다.