# How to upgrade setup-uv in GitHub Actions


To upgrade [setup-uv](https://pydevtools.com/handbook/tutorial/setting-up-github-actions-with-uv.md), 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](https://github.com/astral-sh/setup-uv/releases), choose a stable release, and read its upgrade notes. Resolve that release's tag from a terminal with Git installed:

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

The first column is the commit SHA:

```console
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:

```yaml
- 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](https://pydevtools.com/handbook/how-to/how-to-pin-github-actions-by-sha-for-python-projects.md) 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:

```yaml
- 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](https://pydevtools.com/handbook/how-to/how-to-cache-uvx-tools-in-github-actions.md). For project installs, follow [how to cache uv dependencies in CI](https://pydevtools.com/handbook/how-to/how-to-cache-uv-dependencies-in-ci.md).

If a workflow uses a custom download manifest, compare its inputs and manifest against the [current customization documentation](https://github.com/astral-sh/setup-uv/blob/main/docs/customization.md) 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](https://pydevtools.com/handbook/how-to/how-to-pin-github-actions-by-sha-for-python-projects.md) so future releases arrive as reviewable updates. Review their release notes and CI results before merging.