uv를 안정적으로 도입하는 법

uv는 젊지만 이미 단단한 도구야. 아래 원칙을 따르면 예상 밖의 문제를 줄이며 도입할 수 있어.

venv를 직접 활성화하는 대신 uv run을 써. 가장 큰 작업 흐름 변화야. 'cd project; uv run pytest'가 'cd project; source .venv/bin/activate; pytest; deactivate' 전체를 대신해. 새 습관으로 익혀 두면 돼.

uv python pin으로 Python 버전을 고정해. .python-version을 작성하고 uv.lock과 결합하면 여러 컴퓨터에서 같은 프로젝트 환경을 재현할 수 있어.

uv.lock을 버전 관리에 포함해. 다른 lockfile과 같은 원칙이야. uv.lock은 텍스트 기반이고 안정적이며 Git에 잘 맞아. 재현성을 위한 파일이므로 gitignore에 넣으면 안 돼.

CI에서는 uv sync를 써. npm ci나 pnpm install --frozen-lockfile처럼 빠르고 엄격하게 설치하며 lockfile이 달라지면 실패해.

한 번 쓸 도구에는 uvx를 써. pipx run과 Python 도구용 npx를 대신해. uvx ruff check .는 프로젝트 의존성에 ruff를 추가하지 않고도 실행해.

기존 프로젝트는 uv pip부터 옮겨. 아직 uv add와 uv.lock을 쓰는 uv 고유 흐름으로 바꿀 수 없다면 uv pip install ...만으로 작업 방식은 그대로 두고 10~100배 빠른 설치를 얻을 수 있어. 먼저 호환 경로를 적용하고 나중에 uv 고유 방식으로 옮겨.

Code

GitHub Actions에서 uv 설치·yaml

# .github/workflows/ci.yml
name: ci
on: [push, pull_request]
jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v5
      - uses: astral-sh/setup-uv@v3
        with:
          enable-cache: true
      - run: uv sync --frozen        # strict; lockfile drift 에 fail
      - run: uv run pytest
      - run: uv run mypy .

pip 프로젝트를 uv 고유 방식으로 이전·bash

# 기존 pip 프로젝트에서
cd my-pip-project

# 단계 1 — uv 초기화 (없으면 pyproject.toml 생성)
uv init --no-readme --bare

# 단계 2 — requirements.txt import
cat requirements.txt | xargs uv add

# 단계 3 — 검증, 실행, commit
uv run python -c "import myproject"
uv lock                           # uv.lock 생성
git add pyproject.toml uv.lock
git commit -m "chore: migrate to uv"

Code

External links

Exercise

Progress

댓글 0