uv란 무엇인가?

2024년 초 Astral(Ruff 개발사)이 공개한 uv는 Rust로 작성된 Python 패키지 관리자로, 2025~2026년 현재 파이썬 생태계에서 가장 주목받는 도구다. pip, pip-tools, pipx, poetry, pyenv, virtualenv 등 여러 도구가 분산해 담당하던 기능을 단일 바이너리 하나로 통합했다.

2026년 기준 새로운 Python 프로젝트의 상당수가 uv를 기본 도구로 채택할 만큼 빠르게 표준으로 자리잡고 있다. pip에 비해 패키지 설치 속도가 캐시 유무에 따라 8~115배 빠르다는 벤치마크 결과가 이미 공개되어 있다.

pip 대비 성능 비교

아래 수치는 공식 BENCHMARKS.md 및 커뮤니티 테스트를 종합한 수치다.

시나리오	pip	uv	속도 향상
pandas 단독 설치	2.6초	1.2초	약 2배
numpy + scipy + torch	14.8초	3.5초	약 4.2배
requirements.txt 50+ 패키지	28.4초	5.1초	약 5.6배
캐시 워밍 후 재설치	기준	-	최대 115배

성능 차이는 Rust의 병렬 다운로드, 메타데이터 적극 캐싱, 그리고 컴파일된 언어로 작성된 의존성 리졸버 덕분이다. CPU 사용률도 pip(92%) 대비 uv(68%)로 낮다.

설치 방법

uv는 별도로 Python이나 Rust 환경이 없어도 설치할 수 있다.

macOS / Linux

# 공식 설치 스크립트
curl -LsSf https://astral.sh/uv/install.sh | sh

# 또는 pip으로 설치
pip install uv

# 또는 Homebrew (macOS)
brew install uv

Windows

powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

설치 후 버전 확인:

uv --version
# uv 0.6.x (2025+ 기준)

핵심 명령어 완전 정리

1. 프로젝트 시작

# 새 프로젝트 초기화 (pyproject.toml + .venv 자동 생성)
uv init my-project
cd my-project

# 현재 디렉터리를 프로젝트로 초기화
uv init .

uv init 실행 시 생성되는 구조:

my-project/
  pyproject.toml   # 프로젝트 메타데이터 + 의존성 목록
  uv.lock          # 정확한 버전 잠금 파일
  .venv/           # 가상환경 (자동 생성)
  .python-version  # Python 버전 고정
  src/             # 소스 코드 디렉터리

2. 패키지 관리

# 패키지 추가 (pyproject.toml에 기록 + 설치)
uv add requests
uv add "fastapi>=0.100"
uv add "numpy==2.0.*"

# 개발 의존성 추가
uv add --dev pytest black ruff

# 패키지 제거
uv remove requests

# 모든 의존성 동기화 (lockfile 기준)
uv sync

# 개발 의존성 제외하고 동기화
uv sync --no-dev

3. 스크립트 실행

# 프로젝트 가상환경 안에서 명령 실행 (activate 불필요)
uv run python main.py
uv run pytest
uv run uvicorn app:main --reload

# 임시 환경에서 한 번만 실행
uvx ruff check .
uvx black --check .

4. Python 버전 관리 (pyenv 대체)

# Python 버전 설치
uv python install 3.11 3.12 3.13

# 사용 가능한 Python 목록 확인
uv python list

# 특정 버전으로 가상환경 생성
uv venv --python 3.12

# 프로젝트에 Python 버전 고정
uv python pin 3.12

5. pip 호환 인터페이스 (기존 워크플로우 유지)

# pip install 그대로 대체
uv pip install requests pandas numpy

# requirements.txt 설치
uv pip install -r requirements.txt

# 가상환경 생성
uv venv .venv

# requirements.txt 동결
uv pip freeze > requirements.txt

# pip compile (pip-tools 대체)
uv pip compile requirements.in -o requirements.txt

6. 도구 설치 (pipx 대체)

# 전역 CLI 도구 설치
uv tool install ruff
uv tool install black
uv tool install httpie

# 임시 실행 (설치 없이 한 번만)
uvx cowsay "Hello uv"

# 설치된 도구 목록
uv tool list

pyproject.toml 구조 예시

uv init으로 생성된 프로젝트의 pyproject.toml 예시다.

[project]
name = "my-project"
version = "0.1.0"
requires-python = ">=3.12"
dependencies = [
    "fastapi>=0.110",
    "pydantic>=2.6",
    "httpx>=0.27",
]

[dependency-groups]
dev = [
    "pytest>=8.0",
    "ruff>=0.4",
    "black>=24.0",
]

[build-system]
requires = ["uv_build"]
build-backend = "uv_build.BuildBackend"

[tool.uv]
python-preference = "managed"

실무 활용 시나리오

시나리오 1: 기존 pip 프로젝트 마이그레이션

# 1. 기존 requirements.txt가 있는 프로젝트에서
uv init .

# 2. 기존 패키지들을 uv로 가져오기
uv add $(cat requirements.txt | grep -v "^#" | tr "\n" " ")

# 3. 또는 pip 호환 명령으로 직접 설치
uv pip install -r requirements.txt

# 4. lockfile 생성
uv lock

시나리오 2: CI/CD 파이프라인 (GitHub Actions)

name: CI
on: [push, pull_request]

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: astral-sh/setup-uv@v4
        with:
          version: "latest"
          enable-cache: true
      - run: uv sync --frozen
      - run: uv run pytest

시나리오 3: Docker 이미지 최적화

FROM python:3.12-slim

# uv 설치
COPY --from=ghcr.io/astral-sh/uv:latest /uv /usr/local/bin/uv

WORKDIR /app
COPY pyproject.toml uv.lock ./

# 의존성만 먼저 설치 (레이어 캐시 활용)
RUN uv sync --frozen --no-dev

COPY . .
CMD ["uv", "run", "uvicorn", "app:main", "--host", "0.0.0.0"]

시나리오 4: 인라인 의존성으로 스크립트 단독 실행

#!/usr/bin/env -S uv run
# /// script
# requires-python = ">=3.12"
# dependencies = [
#   "requests",
#   "rich",
# ]
# ///

import requests
from rich.console import Console

console = Console()
resp = requests.get("https://api.github.com")
console.print(f"GitHub API status: {resp.status_code}")

이 스크립트는 uv run script.py로 실행하면 가상환경 설정 없이 바로 동작한다. 일회성 자동화 스크립트나 배포 스크립트에 유용하다.

uv workspace: 모노레포 지원

대규모 프로젝트에서 자주 쓰는 모노레포 구조를 uv workspace로 구성할 수 있다.

# 워크스페이스 루트 구조
my-monorepo/
  pyproject.toml        # 워크스페이스 루트 설정
  packages/
    api/pyproject.toml  # 서브 패키지 A
    core/pyproject.toml # 서브 패키지 B
    worker/pyproject.toml

# 루트 pyproject.toml
[tool.uv.workspace]
members = ["packages/*"]

# 전체 워크스페이스 동기화
uv sync

# 특정 패키지만 실행
uv run --package api uvicorn app:main

uv + Ruff 조합: 완전한 Python 개발 환경

uv와 같은 Astral 팀이 개발한 Ruff를 함께 사용하면 린터+포매터까지 단일 스택으로 통합된다.

# 개발 도구 추가
uv add --dev ruff

# 코드 린팅
uv run ruff check .

# 코드 포매팅
uv run ruff format .

# pyproject.toml에 Ruff 설정
# [tool.ruff]
# line-length = 100
# target-version = "py312"

자주 쓰는 명령어 요약

기능	기존 도구	uv 명령
패키지 설치	pip install X	uv add X
가상환경 생성	python -m venv .venv	uv venv
스크립트 실행	source .venv/bin/activate && python	uv run python
Python 설치	pyenv install 3.12	uv python install 3.12
글로벌 CLI 도구	pipx install black	uv tool install black
의존성 동결	pip freeze > req.txt	uv lock
환경 재현	pip install -r req.txt	uv sync
임시 도구 실행	npx (Node.js 방식 없음)	uvx ruff

마치며

uv는 Python 개발 환경의 분산된 복잡함을 단일 도구로 정리하면서도 압도적인 속도를 제공한다. pip를 쓰던 개발자라면 명령어 앞에 uv만 붙이는 것에서 시작해 점진적으로 uv init 기반의 프로젝트 구조로 이행할 수 있다. 특히 CI/CD, Docker, 모노레포 환경에서 체감 효과가 크다.

2026년 현재 Astral의 꾸준한 업데이트와 넓어지는 커뮤니티 지지를 고려할 때, uv는 Python 생태계의 사실상 표준 패키지 관리자로 자리잡았다고 볼 수 있다.