uv Wisdom

uv is young but solid. These rules let you adopt it without surprises.

Use uv run instead of activating venvs. The single biggest workflow shift. 'cd project; uv run pytest' replaces 'cd project; source .venv/bin/activate; pytest; deactivate'. Build the muscle memory; the old one becomes obsolete.

Pin your Python version with uv python pin. Writes .python-version. Combined with uv.lock, your project is reproducible across machines.

Commit uv.lock. Same rule as every other lockfile in this quest. uv.lock is text, fairly stable, git-friendly. It IS your reproducibility — don't gitignore it.

Use uv sync in CI. Same role as npm ci or pnpm install --frozen-lockfile: strict, fast, fails on lockfile drift.

Use uvx for one-off tools. Replaces pipx run and npx for Python tools. uvx ruff check . works without committing ruff to your project.

The drop-in uv pip path is your migration. If a project isn't ready to switch to uv-native (uv add + uv.lock), uv pip install ... is a 10-100x speedup with zero workflow change. Do that first; migrate to uv-native later.

Code

GitHub Actions: uv as the install step·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; fails if lockfile drift
      - run: uv run pytest
      - run: uv run mypy .

Migrate a pip project to uv-native·bash

# In an existing pip project
cd my-pip-project

# Step 1 — initialize uv (creates pyproject.toml if missing)
uv init --no-readme --bare

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

# Step 3 — verify, run, commit
uv run python -c "import myproject"
uv lock                           # generates uv.lock
git add pyproject.toml uv.lock
git commit -m "chore: migrate to uv"

Code

External links

Exercise

Progress

Comments 0