mirror of https://github.com/astral-sh/setup-uv.git synced 2026-08-14 06:00:30 +02:00

Files

T

Kevin StillhammerandGitHub 18d451d679 Add latest-known version selector (#993 )

## Summary

- add `latest-known` as an explicit version selector
- resolve it locally to the newest version in the bundled checksum table
- preserve existing default and `latest` behavior
- document custom-manifest checksum semantics and update published
bundles

## Testing

- `npm ci --ignore-scripts`
- `npm run all` (99 tests passed)

Closes #919

Refs: pi-session 019fed0e-6019-7504-911b-bd9955cbbd49

2026-08-11 11:15:59 +02:00

3.7 KiB

Raw Blame History

Advanced Version Configuration

This document covers advanced options for configuring which version of uv to install.

Install the latest version

- name: Install the latest version of uv
  uses: astral-sh/setup-uv@c771a70e6277c0a99b617c7a806ffedaca235ff9 # v9.0.0
  with:
    version: "latest"

Install the latest version with a checksum verified by this action

Use latest-known to install the newest uv version whose checksums were bundled with the version of setup-uv used by your workflow. Version resolution is performed locally without fetching the latest release, so updating setup-uv also updates the version selected by latest-known.

When manifest-file is set, latest-known still selects a version from setup-uv's bundled checksum table, but the artifact and checksum come from the custom manifest.

- name: Install the latest version of uv known to setup-uv
  uses: astral-sh/setup-uv@c771a70e6277c0a99b617c7a806ffedaca235ff9 # v9.0.0
  with:
    version: "latest-known"

Install a specific version

- name: Install a specific version of uv
  uses: astral-sh/setup-uv@c771a70e6277c0a99b617c7a806ffedaca235ff9 # v9.0.0
  with:
    version: "0.4.4"

Install a version by supplying a semver range or pep440 specifier

You can specify a semver range or pep440 specifier to install the latest version that satisfies the range.

- name: Install a semver range of uv
  uses: astral-sh/setup-uv@c771a70e6277c0a99b617c7a806ffedaca235ff9 # v9.0.0
  with:
    version: ">=0.4.0"

- name: Pinning a minor version of uv
  uses: astral-sh/setup-uv@c771a70e6277c0a99b617c7a806ffedaca235ff9 # v9.0.0
  with:
    version: "0.4.x"

- name: Install a pep440-specifier-satisfying version of uv
  uses: astral-sh/setup-uv@c771a70e6277c0a99b617c7a806ffedaca235ff9 # v9.0.0
  with:
    version: ">=0.4.25,<0.5"

Resolution strategy

By default, when resolving version ranges, setup-uv will install the highest compatible version. You can change this behavior using the resolution-strategy input:

- name: Install the lowest compatible version of uv
  uses: astral-sh/setup-uv@c771a70e6277c0a99b617c7a806ffedaca235ff9 # v9.0.0
  with:
    version: ">=0.4.0"
    resolution-strategy: "lowest"

The supported resolution strategies are:

highest (default): Install the latest version that satisfies the constraints
lowest: Install the oldest version that satisfies the constraints

This can be useful for testing compatibility with older versions of uv, similar to uv's own --resolution-strategy option.

Install a version defined in a requirements or config file

You can use the version-file input to specify a file that contains the version of uv to install. This can either be a pyproject.toml or uv.toml file which defines a required-version or uv defined as a dependency in pyproject.toml or requirements.txt.

asdf .tool-versions is also supported, but without the ref syntax.

- name: Install uv based on the version defined in pyproject.toml
  uses: astral-sh/setup-uv@c771a70e6277c0a99b617c7a806ffedaca235ff9 # v9.0.0
  with:
    version-file: "pyproject.toml"

If uv is locked as a dependency in your uv.lock, you can point version-file at the lockfile to install the exact pinned version. This keeps CI runs deterministic and avoids silently picking up a newer uv until the lockfile is updated.

- name: Install uv based on the version locked in uv.lock
  uses: astral-sh/setup-uv@c771a70e6277c0a99b617c7a806ffedaca235ff9 # v9.0.0
  with:
    version-file: "uv.lock"

3.7 KiB Raw Blame History