How to Cache the uv Cache in GitHub Actions

Cache uv's global cache directory keyed on uv.lock so uv sync reuses already-downloaded wheels.

uv keeps a global cache of downloaded and built wheels. The astral-sh/setup-uv action can enable caching directly, or you can cache the directory from uv cache dir yourself keyed on uv.lock.

Steps

• Install uv with astral-sh/setup-uv and set enable-cache: true, or cache manually.
• For a manual cache, resolve the path with uv cache dir.
• Key the cache on hashFiles('**/uv.lock').
• Run uv sync --frozen.

Workflow

steps:
  - uses: actions/checkout@v4
  - id: uv
    run: |
      curl -LsSf https://astral.sh/uv/install.sh | sh
      echo "dir=$(uv cache dir)" >> "$GITHUB_OUTPUT"
  - uses: actions/cache@v4
    with:
      path: ${{ steps.uv.outputs.dir }}
      key: uv-${{ runner.os }}-${{ hashFiles('**/uv.lock') }}
      restore-keys: |
        uv-${{ runner.os }}-
  - run: uv sync --frozen

Gotchas

• The astral-sh/setup-uv action with enable-cache: true handles the cache path and key for you.
• Use uv sync --frozen so CI fails on lockfile drift rather than silently re-resolving.

Related guides