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

Files

T

Kevin StillhammerandGitHub 46f427bd47 Read Python version from .tool-versions (#996 )

## Summary
- read the Python version from an explicitly selected `.tool-versions`
file
- preserve `python-version` and existing `UV_PYTHON` precedence
- add parser, input, and workflow coverage and update documentation and
bundled action artifacts

## Validation
- `npm run all`
- `actionlint .github/workflows/test.yml`
- `uvx zizmor .github/workflows/test.yml`

Closes #983

Refs: pi-session 019ff01a-544c-79f3-8f73-a00132af39f5

2026-08-11 14:26:03 +02:00

3.9 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 for selecting uv. If neither python-version nor UV_PYTHON is set, the python entry from the selected file is also exported as UV_PYTHON. Only a single Python version is supported; multiple fallback versions and the asdf ref:, path:, and system forms are ignored with a warning.

- 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.9 KiB Raw Blame History