mirror of https://github.com/astral-sh/setup-uv.git synced 2026-06-19 11:02:23 +00:00

Files

T

somaz 3faa3174e6 feat: support uv.lock as a version-file source (#918 )

Adds `uv.lock` as a supported `version-file` source. When `uv` is locked
as a
dependency in `uv.lock`, the action now installs the exact pinned
version,
closing the gap reported in #682.

This is useful for deterministic CI: the same uv version is used until
the
lockfile is updated, which avoids "CI worked yesterday, fails today"
drift and
reduces supply-chain exposure from auto-installing the latest release.

The implementation mirrors the existing `version-file` parsers — a new
`uv.lock`
entry in the parser registry reads the `[[package]]` whose `name = "uv"`
and
returns its locked `version`. Scoped to explicit `version-file:
uv.lock`;
workspace auto-detection is left as a possible follow-up to avoid
precedence
ambiguity with `uv.toml` / `pyproject.toml`.

Validation (local, Node 23; dist build is esbuild-deterministic):
- `npm run all` → build clean, biome clean, package clean, jest 77/77
- New tests: 3 unit (`uv-lock-file.test.ts`) + 1 integration — exact pin
resolves
  through the full pipeline (`uv.lock` → `0.8.17`)
- dist rebuilt + committed (single bundle, no spurious churn)

related: #682

2026-06-19 07:08:57 +02:00

3.0 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@08807647e7069bb48b6ef5acd8ec9567f424441b # v8.1.0
  with:
    version: "latest"

Install a specific version

- name: Install a specific version of uv
  uses: astral-sh/setup-uv@08807647e7069bb48b6ef5acd8ec9567f424441b # v8.1.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@08807647e7069bb48b6ef5acd8ec9567f424441b # v8.1.0
  with:
    version: ">=0.4.0"

- name: Pinning a minor version of uv
  uses: astral-sh/setup-uv@08807647e7069bb48b6ef5acd8ec9567f424441b # v8.1.0
  with:
    version: "0.4.x"

- name: Install a pep440-specifier-satisfying version of uv
  uses: astral-sh/setup-uv@08807647e7069bb48b6ef5acd8ec9567f424441b # v8.1.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@08807647e7069bb48b6ef5acd8ec9567f424441b # v8.1.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@08807647e7069bb48b6ef5acd8ec9567f424441b # v8.1.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@08807647e7069bb48b6ef5acd8ec9567f424441b # v8.1.0
  with:
    version-file: "uv.lock"

3.0 KiB Raw Blame History