Rye & uv 완벽 가이드 — Python 패키징을 Rust 속도로, pip·poetry·pyenv 대체

설치

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

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

# pip (비권장 — 부트스트랩용)
pip install uv

uv --version

첫 프로젝트

uv init my-app
cd my-app

uv add fastapi uvicorn
uv add --dev pytest ruff

uv run main.py
uv run pytest

• uv init: pyproject.toml + uv.lock 생성
• uv add: 의존성 추가 + 가상환경 자동 생성
• uv run: 가상환경 안에서 명령 실행

pyproject.toml

[project]
name = "my-app"
version = "0.1.0"
description = "My Python app"
requires-python = ">=3.11"
dependencies = [
    "fastapi>=0.115",
    "uvicorn[standard]>=0.32",
]

[project.optional-dependencies]
dev = [
    "pytest>=8.3",
    "ruff>=0.8",
]

[build-system]
requires = ["hatchling"]
build-backend = "hatchling.build"

[tool.uv]
dev-dependencies = ["ipython>=8.20"]

[tool.ruff]
line-length = 100

uv add가 dependencies를 자동 수정.

가상환경

# 가상환경 생성
uv venv

# 활성화
source .venv/bin/activate    # Linux/macOS
.venv\Scripts\activate       # Windows

# uv run으로 활성화 생략 가능
uv run python script.py
uv run pytest

uv venv는 초고속(1초 미만). Python 버전도 uv venv --python 3.12로 명시.

Python 버전 관리 (pyenv 대체)

# Python 설치 (여러 버전 공존)
uv python install 3.12 3.11 3.10

# 프로젝트별 고정
uv python pin 3.12

# 버전 확인
uv python list
uv python find 3.11

.python-version 파일을 생성해 uv·pyenv·mise 모두 인식합니다.

의존성 설치

# pyproject.toml 기반
uv sync                          # install + lock 갱신

# requirements.txt 레거시
uv pip install -r requirements.txt

# 글로벌 도구 (pipx 대체)
uv tool install ruff
uv tool install black
uv tool run ruff check .

lock 파일 (uv.lock)

• uv sync가 uv.lock 생성/갱신
• 플랫폼·Python 버전별 해시 포함
• 팀원·CI가 정확히 같은 버전 설치

Poetry의 poetry.lock와 유사하지만 훨씬 빠르게 해결.

워크스페이스 (Monorepo)

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

[tool.uv]
dev-dependencies = ["pytest>=8.3"]

# packages/core/pyproject.toml
[project]
name = "my-core"
version = "0.1.0"
dependencies = []

uv sync           # 루트에서 모든 워크스페이스 동시 설치
uv run --package my-core pytest

pnpm workspaces 같은 경험이 Python에 온 것.

Docker 통합

FROM python:3.12-slim AS builder
WORKDIR /app
COPY --from=ghcr.io/astral-sh/uv:latest /uv /bin/uv
ENV UV_COMPILE_BYTECODE=1 UV_LINK_MODE=copy
COPY pyproject.toml uv.lock ./
RUN --mount=type=cache,target=/root/.cache/uv \
    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", "main.py"]

uv 캐시로 CI 빌드가 극적으로 빨라집니다.

CI: GitHub Actions

- uses: astral-sh/setup-uv@v4
  with:
    enable-cache: true
    cache-dependency-glob: "uv.lock"

- run: uv sync --frozen
- run: uv run pytest
- run: uv run ruff check .

uv 바이너리 다운로드 + 캐싱까지 자동 처리.

Ruff와의 조합

uv add --dev ruff
uv run ruff check .
uv run ruff format .

Astral 팀이 같이 만들어 통합이 완벽합니다.

비교 요약

도구	속도	기능	표준
pip	느림	기본	PyPI 표준
poetry	느림	풍부	자체 lock
pipenv	느림	기본+	Pipfile
uv	극도로 빠름	풍부	pyproject.toml

트러블슈팅

uv sync 실패

• --frozen 없이 uv sync로 lock 재해결
• uv cache clean 후 재시도

Python 버전 안 잡힘

• uv python install 3.12로 명시 설치
• .python-version 또는 requires-python 확인

특정 패키지 빌드 실패

• 컴파일러(gcc, clang) 필요한 패키지 → 시스템 의존성 설치
• uv pip install --no-binary :all: 로 소스 빌드 강제

Docker에서 느림

• --mount=type=cache,target=/root/.cache/uv로 캐시 마운트
• multi-stage build로 빌드 아티팩트 분리

체크리스트

• uv 설치 + shell PATH 확인
• uv init + pyproject.toml 표준화
• uv.lock 커밋
• uv sync --frozen CI 적용
• Python 버전 uv python install + pin
• 글로벌 도구 uv tool install
• Ruff 통합 (린트·포맷)
• Docker에 uv 캐시 마운트

마무리

uv는 Python 패키징 생태계에 Rust 속도를 가져온 혁명적 도구입니다. pip·poetry·pyenv가 각자 해결하던 문제를 단일 바이너리로 통합하면서 속도는 10-100배 빨라졌습니다. Astral 팀의 Ruff·Ruff-lsp에 이어 uv가 표준이 되면서 “Python 도구 체인의 느림”이라는 오래된 불만이 완전히 해소되고 있습니다. 기존 pip·poetry 프로젝트도 uv sync 한 번으로 이주 체험이 가능하니, 지금 바로 CI 빌드 시간 측정과 함께 도입을 시도해보길 권장합니다.

관련 글

• Python 완벽 가이드
• Poetry 완벽 가이드
• Ruff 린터/포매터 가이드
• mise 런타임 버전 관리 가이드