How to upgrade setup-uv in GitHub Actions

To upgrade setup-uv, replace its tag or commit SHA in your GitHub Actions workflows and check the cache settings. A moving tag such as @v7 does not track current releases.

Select a release and resolve its commit

Open the setup-uv releases page, choose a stable release, and read its upgrade notes. Resolve that release’s tag from a terminal with Git installed:

git ls-remote https://github.com/astral-sh/setup-uv refs/tags/v10.1.0

The first column is the commit SHA:

bec219d24cd3e171d82865faccec33120bb574f4  refs/tags/v10.1.0

Use the tag you selected when checking a different release. Current releases use full-version tags; references such as @v10 or @v10.1 do not resolve.

Replace the reference in each workflow

In each file under .github/workflows/, replace the uses: line while keeping the job’s existing inputs:

- uses: astral-sh/setup-uv@bec219d24cd3e171d82865faccec33120bb574f4  # v10.1.0

Keep the full version comment beside the SHA so reviewers and update tools can identify the release. A full tag such as astral-sh/setup-uv@v10.1.0 also works; pinning GitHub Actions by SHA applies GitHub’s recommendation for third-party actions.

Review cache settings before running the workflow

The defaults keep the downloaded cache intact and enable caching on GitHub-hosted runners except for release, tag pushes, pull_request_target, and workflow_run. Those exclusions protect jobs from restoring potentially poisoned caches.

Make the choices explicit when reviewing an existing workflow:

- uses: astral-sh/setup-uv@bec219d24cd3e171d82865faccec33120bb574f4  # v10.1.0
  with:
    enable-cache: auto
    prune-cache: false

For an ordinary test job, enable-cache: true enables caching explicitly, including on self-hosted runners. It also overrides the event exclusions, so keep auto or use false for release and privileged jobs unless their cache trust boundary has been reviewed.

Set prune-cache: true only when the job should discard pre-built wheels before saving its cache. Keep it false for cached uvx tools. For project installs, follow how to cache uv dependencies in CI.

If a workflow uses a custom download manifest, compare its inputs and manifest against the current customization documentation before upgrading.

Run the workflow and keep updates enabled

Push the workflow change on a branch and inspect its Actions run. Confirm that setup-uv installs the requested uv version, the project’s checks pass, and the cache restore/save steps match the intended policy. Recheck every operating system in the workflow’s matrix.

Enable the github-actions ecosystem in Dependabot’s weekly configuration so future releases arrive as reviewable updates. Review their release notes and CI results before merging.