Dockerized Flask / Django 앱에서 Pip을 Uv로 전환하기

15 hours ago 1

uv로 전환 시 프로젝트의 Python 의존성 설치 속도가 약 10배 빨라짐
기존 requirements.txt 대신 pyproject.toml 사용, 상위 의존성만 기록하고 uv가 자동으로 lock 파일 생성
Docker 환경에서는 venv를 사용하지 않으며, 비 root 사용자로 모든 Python 패키지 설치 가능
uv sync, add, remove와 같은 명령어로 쉽게 의존성 추가·삭제·업데이트 가능
규칙적으로 lock 파일 관리 및 의존성 업데이트가 가능해져 협업 및 배포 환경에서 일관성 확보에 장점 존재

개요

uv는 기존 pip 대비 Python 프로젝트의 의존성 설치 속도를 크게 개선하는 툴임. Docker 기반 Flask/Django 앱에서 pip을 uv로 전환하면, 약 10배 빠른 실행 속도를 경험할 수 있음. 추가적으로 venv 없이 비 root 권한 사용자 상태로 Python 패키지를 안전하게 설치하도록 구성 가능함.

pyproject.toml vs requirements.txt

의존성 관리는 이제 pyproject.toml 파일로 전환
- project.dependencies 항목에 상위 의존성만 입력
- 기존 requirements.txt는 삭제
- uv 사용 시 lock 파일 자동 생성 및 관리
uv의 lock 파일은 의존성 트리 정보를 정확하게 포함하며, pip freeze에 비해 신뢰도가 높음

Dockerfile 변경 사항

uv 설치

Dockerfile 내에서, 미리 빌드된 uv 및 uvx 바이너리를 컨테이너로 복사
- 예시: COPY --from=ghcr.io/astral-sh/uv:0.7.13 /uv /uvx /usr/local/bin/
시스템 PATH에 uv, uvx가 모두 존재해야 함

의존성 파일 복사

pyproject.toml 및 uv.lock* 파일 복사
- 첫 빌드 시 uv.lock이 없을 수 있으므로 *을 붙여 lock 파일 복사 생략 가능하게 처리

환경 변수 설정

UV_COMPILE_BYTECODE=1 지정 시 모든 소스 파일이 빌드 단계에서 바이트코드로 변환
- 컨테이너 시작 시 컴파일 없음
UV_PROJECT_ENVIRONMENT 지정으로 venv 생성 없이 패키지 설치 위치 직접 관리 가능
- 예시: /home/python/.local

의존성 설치 명령 변경

기존: pip3-install 스크립트
변경: uv-install 스크립트
- uv lock 파일 확인 및 갱신/생성
- uv sync로 정확히 지정된 버전만 설치
- --frozen 옵션: lock 파일의 내용을 변경하지 않고 그대로 사용
- --no-install-project 옵션: 자체 프로젝트 패키지화 생략

의존성 추가, 업데이트, 삭제 방법

run script를 통한 의존성 관리 자동화
- ./run deps:install: 도커 이미지를 빌드하고, 최신 lock 파일 갱신
- ./run deps:install --no-build: 새 lock 파일만 호스트에 반영, 빌드는 생략
- ./run uv [...]: 도커 컨테이너 내부에서 any uv 명령 실행, 예) add, remove
  - uv add mypackage --no-sync: pyproject.toml과 lock 파일만 갱신, 설치는 별도 실행(install)
  - uv remove mypackage --no-sync: 패키지 제거
- ./run uv:outdated: 현재 의존성 중 업데이트 가능한 패키지 목록 확인

데모 영상 안내

영상은 사용 방법 및 주요 변경점 시연 포함
- 타임스탬프별로 pyproject.toml, Dockerfile, uv 명령어 등 주요 흐름 소개

요약

pip 대신 uv를 채택하면, Docker 환경에서도 쉽게 더 빠르고 일관성 있는 Python 의존성 관리를 구현할 수 있음. venv 미사용, lock 파일 자동화, shell script 및 run script 활용 등 협업 환경에서의 업무 효율성도 크게 향상됨.

Read Entire Article