uv — Python 패키지 매니저

uv 는 Python 의 패키지 · 프로젝트 매니저 가운데 가장 늦게 등장한 축. 이 글은 uv 의 출자 · 역할 · 기존 도구와의 관계를 사실 기준으로 정리합니다.

1. uv 에 대한 이야기

Astral 이 개발하는 오픈소스 도구. Rust 로 작성. 같은 회사가 만드는 Python 린터 Ruff 의 자매 프로젝트. 2024 년 2월 첫 공개 릴리스 (0.1.0), 같은 해 0.4 부터 프로젝트 매니저 기능 (uv add · uv sync · uv run) 이 정식 도입. 라이선스는 MIT / Apache 2.0 이중.

공식 문서의 한 줄 — "An extremely fast Python package and project manager, written in Rust." pip / pip-tools / virtualenv 명령의 드롭인 대체와 Poetry / PDM 류의 프로젝트 워크플로를 한 도구에 합치는 방향.

2. 두 가지 모드

uv 의 모드는 크게 둘:

1. pip 호환 모드 (uv pip ...) — 기존 pip install · pip-compile · python -m venv 흐름을 같은 인터페이스로 더 빠르게 실행. CI 가 pip 만 가정해도 거의 그대로 갈아끼울 수 있음.
2. 프로젝트 모드 (uv add · uv sync · uv run) — pyproject.toml (PEP 621) 의 [project] 메타데이터와 uv.lock 락파일을 SSOT 로 삼아 의존성 관리.

3. Python 인터프리터 관리

Python 인터프리터 자체도 uv 가 관리. uv python install 3.12 같은 명령으로 시스템과 분리된 인터프리터를 받아 두고, 프로젝트마다 .python-version 으로 고정. 이 부분은 pyenv 가 하던 일과 겹침.

가상환경은 기본적으로 프로젝트 안의 .venv/ 에. uv run <cmd> 는 이 가상환경을 활성화한 상태로 명령 실행.

4. 다른 길

도구	첫 릴리스	위치
pip	2008	Python 표준 의존성 설치기. PyPA 관리.
virtualenv	2007	Ian Bicking. 격리 환경 생성. 후에 표준 venv 모듈 (2012, Python 3.3) 로 일부 흡수.
pip-tools	2012	pip-compile 로 락파일 (requirements.txt 고정 버전) 생성.
Poetry	2018	Sébastien Eustace. pyproject.toml + poetry.lock 워크플로.
PDM	2021	PEP 582 실험 포함. pyproject.toml 표준 충실.
Hatch	2022 (재작성)	PyPA 가 추천. 빌드 · 환경 · 퍼블리시.
uv	2024	Astral. Rust. 위 도구들의 기능을 한 도구로 묶고 속도 강조.

선택은 환경에 따라 갈림. 기존 코드베이스가 Poetry 로 잘 돌고 있다면 굳이 갈아탈 필요는 작음. 신규 프로젝트나 CI 시간이 병목인 경우 uv 가 자주.

5. 자주 쓰는 모양

# 설치
# Windows (PowerShell)
irm https://astral.sh/uv/install.ps1 | iex
# macOS · Linux
curl -LsSf https://astral.sh/uv/install.sh | sh

# 프로젝트 시작
uv init my-app
cd my-app
uv add fastapi "uvicorn[standard]"
uv add --dev pytest ruff

# 실행
uv run python -m uvicorn app:app --reload
uv run pytest

# 동기화 (락파일 기준 정확 재현)
uv sync                       # 개발 의존 포함
uv sync --frozen --no-dev     # CI · Docker 권장

pyproject.toml 예:

[project]
name = "my-app"
version = "0.1.0"
requires-python = ">=3.12"
dependencies = ["fastapi>=0.115", "uvicorn[standard]>=0.30"]

[dependency-groups]
dev = ["pytest>=8", "ruff>=0.6"]

6. Docker 멀티스테이지

FROM python:3.12-slim AS builder
COPY --from=ghcr.io/astral-sh/uv:latest /uv /uvx /usr/local/bin/
WORKDIR /app
COPY pyproject.toml uv.lock ./
RUN uv sync --frozen --no-dev

FROM python:3.12-slim
WORKDIR /app
COPY --from=builder /app/.venv /app/.venv
COPY . .
ENV PATH="/app/.venv/bin:$PATH"
CMD ["python", "-m", "uvicorn", "app:app", "--host", "0.0.0.0"]

7. 자주 걸리는 자리

활동적인 개발 단계 — 마이너 버전 사이에 동작 차이가 발생할 수 있음. CI 와 로컬 모두에서 uv 버전을 고정하는 편이 재현성에 도움.

uv.lock 은 universal lockfile — 여러 플랫폼 · Python 버전을 한 파일에. Poetry 의 락파일 형식과 호환 안 됨. 마이그레이션 시 uv add 로 다시 해소.

uv pip install -r requirements.txt 는 가능하지만, 그 결과가 uv.lock 에 자동 반영되지는 않음. 두 흐름을 한 프로젝트에 섞으면 SSOT 가 흔들림.

일부 패키지는 wheel 이 없는 Python 버전 조합에서 소스 빌드가 필요. uv 가 호출하는 빌드 백엔드는 결국 setuptools / maturin 등이라 같은 종류의 빌드 도구 · 헤더가 필요.

하고픈 말

uv 는 pip 호환 + 프로젝트 매니저 + 인터프리터 관리를 한 도구로 합친 빠른 답. Rust 로 작성된 속도가 CI 에서 체감이 큽니다. Poetry · pip-tools · pyenv 셋이 분담하던 자리를 한 명령어 대역으로 이전. 다만 활동적인 개발 단계라 버전 고정이 안전한 자리.

Next

• env-and-secrets
• version-managers

uv 공식 문서 · uv llms.txt · uv GitHub · Astral 블로그 uv 공개 글 · PEP 621 · PyPA Packaging User Guide · Poetry 공식 문서 · Ruff 공식 문서 를 참고합니다.