mirror of
https://github.com/astral-sh/setup-uv.git
synced 2026-06-19 19:12:26 +00:00
somaz
3faa3174e6
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
94 lines
3.0 KiB
Markdown
94 lines
3.0 KiB
Markdown
# Advanced Version Configuration
|
|
|
|
This document covers advanced options for configuring which version of uv to install.
|
|
|
|
## Install the latest version
|
|
|
|
```yaml
|
|
- name: Install the latest version of uv
|
|
uses: astral-sh/setup-uv@08807647e7069bb48b6ef5acd8ec9567f424441b # v8.1.0
|
|
with:
|
|
version: "latest"
|
|
```
|
|
|
|
## Install a specific version
|
|
|
|
```yaml
|
|
- 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](https://github.com/npm/node-semver?tab=readme-ov-file#ranges)
|
|
or [pep440 specifier](https://peps.python.org/pep-0440/#version-specifiers)
|
|
to install the latest version that satisfies the range.
|
|
|
|
```yaml
|
|
- name: Install a semver range of uv
|
|
uses: astral-sh/setup-uv@08807647e7069bb48b6ef5acd8ec9567f424441b # v8.1.0
|
|
with:
|
|
version: ">=0.4.0"
|
|
```
|
|
|
|
```yaml
|
|
- name: Pinning a minor version of uv
|
|
uses: astral-sh/setup-uv@08807647e7069bb48b6ef5acd8ec9567f424441b # v8.1.0
|
|
with:
|
|
version: "0.4.x"
|
|
```
|
|
|
|
```yaml
|
|
- 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:
|
|
|
|
```yaml
|
|
- 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](https://asdf-vm.com/) `.tool-versions` is also supported, but without the `ref` syntax.
|
|
|
|
```yaml
|
|
- 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.
|
|
|
|
```yaml
|
|
- 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"
|
|
```
|