Python 3.13 + uv + ruff — 모던 Python 워크플로 30분 셋업

핵심 요약

Python 생태계가 2024~2025년에 큰 변화. uv가 pip·poetry·virtualenv를 대체하고, ruff가 black·flake8·isort를 통합. Python 3.13의 free-threading(GIL 제거 옵션)이 본격 도입.

• uv (Astral): 10~100배 빠른 패키지·환경 관리
• ruff: 린터+포매터 통합, 100배 빠름
• Python 3.13 (2024-10): free-threading 옵션, JIT

1. uv — 패키지·환경 관리

# 설치
curl -LsSf https://astral.sh/uv/install.sh | sh

# 새 프로젝트
uv init my-project
cd my-project

# 의존성 추가
uv add fastapi uvicorn sqlalchemy
uv add --dev pytest black

# 가상환경·종속성 한 번에
uv sync

# 실행
uv run python main.py
uv run pytest

2. ruff — 린터+포매터

# pyproject.toml
[tool.ruff]
line-length = 100
target-version = "py313"

[tool.ruff.lint]
select = [
    "E",    # pycodestyle
    "F",    # pyflakes
    "I",    # isort
    "N",    # pep8-naming
    "UP",   # pyupgrade
    "B",    # bugbear
    "C4",   # comprehensions
    "SIM",  # simplify
    "TID",  # tidy imports
]
ignore = ["E501"]

[tool.ruff.format]
quote-style = "double"

# 사용
ruff check .       # 린터
ruff check --fix . # 자동 수정
ruff format .      # 포매터

black·flake8·isort 4개 도구 → ruff 1개. 100배 빠름.

3. Python 3.13 — Free-Threading

# Free-threading 빌드 설치 (3.13t)
uv python install 3.13t

# 사용
uv run --python 3.13t python script.py

import threading
import time

def cpu_bound(n):
    return sum(i*i for i in range(n))

threads = [threading.Thread(target=cpu_bound, args=(10_000_000,)) for _ in range(8)]
for t in threads: t.start()
for t in threads: t.join()
# 3.13t에서 8 core 활용. 일반 3.13은 GIL로 직렬화.

주의: 모든 C 확장이 free-threading 호환은 아님. 점진 전환 중.

4. JIT (3.13 실험)

# JIT 빌드
uv python install --enable-jit 3.13

# 일부 워크로드 5~30% 향상
# 단 JIT compilation 자체에 메모리 비용

5. 모던 패턴 — FastAPI + uv + ruff + pytest

# pyproject.toml
[project]
name = "my-api"
version = "0.1.0"
requires-python = ">=3.13"
dependencies = [
    "fastapi>=0.110",
    "uvicorn[standard]>=0.30",
    "sqlmodel>=0.0.14",
    "httpx>=0.27",
]

[dependency-groups]
dev = [
    "pytest>=8.0",
    "ruff>=0.4",
    "mypy>=1.10",
]

6. 타입 검사 — mypy vs pyright vs ty

7. CI 워크플로 (GitHub Actions)

name: CI
on: [push, pull_request]

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: astral-sh/setup-uv@v3
        with:
          enable-cache: true
      - run: uv sync
      - run: uv run ruff check .
      - run: uv run ruff format --check .
      - run: uv run mypy .
      - run: uv run pytest --cov

uv 캐시로 CI 실행 시간 5분 → 1분.

8. Docker — multi-stage

FROM python:3.13-slim AS builder
COPY --from=ghcr.io/astral-sh/uv:0.4 /uv /uv
WORKDIR /app
COPY pyproject.toml uv.lock ./
RUN uv sync --frozen --no-dev

FROM python:3.13-slim
WORKDIR /app
COPY --from=builder /app/.venv /app/.venv
COPY . .
CMD [".venv/bin/uvicorn", "main:app", "--host", "0.0.0.0"]

9. uv 추가 기능

• uv pip — pip 호환 인터페이스 (마이그레이션 부담 0)
• uv tool install — pipx 대체, 글로벌 도구 설치
• uv python install — Python 자체 설치 (pyenv 대체)
• workspaces — 모노레포 다중 패키지 관리

10. 마이그레이션 — pip+poetry → uv

# requirements.txt → pyproject.toml
uv init
uv add $(cat requirements.txt | grep -v '^#' | tr '\n' ' ')

# poetry → uv
uv tool install poetry-to-uv
poetry-to-uv

실측 — 일일 워크플로

자주 묻는 질문

uv가 정말 poetry를 대체하나?

거의. 단 poetry의 일부 고급 기능 (plugins) 없음. 일반 워크플로는 uv가 압도.

3.13 free-threading 운영 가능?아직 실험적. 3.14에서 안정 예상. 운영은 일반 3.13으로.

ruff vs black + flake8 동시 운영?비추. ruff 하나로 통합 권장. 대형 프로젝트도 1주일이면 마이그레이션.