Set up your Actions workflow with a specific version of uv.

• Install a version of uv and add it to PATH
• Cache the installed version of uv to speed up consecutive runs on self-hosted runners
• Register problem matchers for error output
• (Optional) Persist the uv's cache in the Actions Cache
• (Optional) Verify the checksum of the downloaded uv executable

• Usage
  • Install the latest version (default)
  • Install a specific version
  • Install a version by supplying a semver range
  • Validate checksum
  • Enable Caching
    • Cache dependency glob
  • Local cache path
  • authentication token
  • UV_TOOL_DIR
  • UV_TOOL_BIN_DIR
• How it works
• FAQ

- name: Install the latest version of uv
  uses: astral-sh/setup-uv@v3
  with:
    version: "latest"

For an example workflow, see here.

- name: Install a specific version of uv
  uses: astral-sh/setup-uv@v3
  with:
    version: "0.4.4"

You can also specify a semver range to install the latest version that satisfies the range.

- name: Install a semver range of uv
  uses: astral-sh/setup-uv@v3
  with:
    version: ">=0.4.0"

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

You can also specify a checksum to validate the downloaded file. Checksums up to the default version are automatically verified by this action. The sha256 hashes can be found on the releases page of the uv repo.

- name: Install a specific version and validate the checksum
  uses: astral-sh/setup-uv@v3
  with:
    version: "0.3.1"
    checksum: "e11b01402ab645392c7ad6044db63d37e4fd1e745e015306993b07695ea5f9f8"

If you enable caching, the uv cache will be cached to the Actions Cache. This can speed up runs that reuse the cache by several minutes.

You can optionally define a custom cache key suffix.

- name: Enable caching and define a custom cache key suffix
  id: setup-uv
  uses: astral-sh/setup-uv@v3
  with:
    enable-cache: true
    cache-suffix: "optional-suffix"

When the cache was successfully restored, the output cache-hit will be set to true and you can use it in subsequent steps. For example, to use the cache in the above case:

- name: Do something if the cache was restored
  if: steps.setup-uv.outputs.cache-hit == 'true'
  run: echo "Cache was restored"

If you want to control when the cache is invalidated, specify a glob pattern with the cache-dependency-glob input. The cache will be invalidated if any file matching the glob pattern changes. The glob matches files relative to the repository root.

- name: Define a cache dependency glob
  uses: astral-sh/setup-uv@v3
  with:
    enable-cache: true
    cache-dependency-glob: "**/requirements*.txt"

- name: Define a list of cache dependency globs
  uses: astral-sh/setup-uv@v3
  with:
    enable-cache: true
    cache-dependency-glob: |
      **/requirements*.txt
      **/pyproject.toml

- name: Never invalidate the cache
  uses: astral-sh/setup-uv@v3
  with:
    enable-cache: true
    cache-dependency-glob: ""

This action controls where uv stores its cache on the runner's filesystem by setting UV_CACHE_DIR. It defaults to setup-uv-cache in the TMP dir, D:\a\_temp\uv-tool-dir on Windows and /tmp/setup-uv-cache on Linux/macOS. You can change the default by specifying the path with the cache-local-path input.

- name: Define a custom uv cache path
  uses: astral-sh/setup-uv@v3
  with:
    cache-local-path: "/path/to/cache"

By default, the uv cache is pruned after every run, removing pre-built wheels, but retaining any wheels that were built from source. On -hosted runners, it's typically faster to omit those pre-built wheels from the cache (and instead re-download them from the registry on each run). However, on self-hosted or local runners, preserving the cache may be more efficient. See thedocumentation for more.

If you want to persist the entire cache across runs, disable cache pruning with the prune-cache input.

- name: Don't prune the cache before saving it
  uses: astral-sh/setup-uv@v3
  with:
    enable-cache: true
    prune-cache: false

This action uses the API to fetch the uv release artifacts. To avoid hitting the API rate limit too quickly, an authentication token can be provided via the -token input. By default, the _TOKEN secret is used, which is automatically provided by Actions.

If the default permissions for the token are not sufficient, you can provide a custom token with the necessary permissions.

- name: Install the latest version of uv with a custom  token
  uses: astral-sh/setup-uv@v3
  with:
    -token: ${{ secrets.CUSTOM__TOKEN }}

On Windows UV_TOOL_DIR is set to uv-tool-dir in the TMP dir (e.g. D:\a\_temp\uv-tool-dir). On hosted runners this is on the much faster D: drive.

On all other platforms the tool environments are placed in the default location.

If you want to change this behaviour (especially on self-hosted runners) you can use the tool-dir input:

- name: Install the latest version of uv with a custom tool dir
  uses: astral-sh/setup-uv@v3
  with:
    tool-dir: "/path/to/tool/dir"

On Windows UV_TOOL_BIN_DIR is set to uv-tool-bin-dir in the TMP dir (e.g. D:\a\_temp\uv-tool-bin-dir). On hosted runners this is on the much faster D: drive. This path is also automatically added to the PATH.

On all other platforms the tool binaries get installed to the default location.

If you want to change this behaviour (especially on self-hosted runners) you can use the tool-bin-dir input:

- name: Install the latest version of uv with a custom tool bin dir
  uses: astral-sh/setup-uv@v3
  with:
    tool-bin-dir: "/path/to/tool-bin/dir"

This action downloads uv from the uv repo's official Releases and uses the Actions Toolkit to cache it as a tool to speed up consecutive runs on self-hosted runners.

The installed version of uv is then added to the runner PATH, enabling subsequent steps to invoke it by name (uv).

No. This action is modelled as a drop-in replacement for actions/setup-python when using uv. With setup-uv, you can install a specific version of Python using uv python install rather than relying on actions/setup-python.

For example:

- name: Checkout the repository
  uses: actions/checkout@main
- name: Install the latest version of uv
  uses: astral-sh/setup-uv@v3
  with:
    enable-cache: true
- name: Test
  run: uv run --frozen pytest

To install a specific version of Python, use uv python install:

- name: Install the latest version of uv
  uses: astral-sh/setup-uv@v3
  with:
    enable-cache: true
- name: Install Python 3.12
  run: uv python install 3.12

By default, this action installs the latest version of uv.

If you require the installed version in subsequent steps of your workflow, use the uv-version output:

- name: Checkout the repository
  uses: actions/checkout@main
- name: Install the default version of uv
  id: setup-uv
  uses: astral-sh/setup-uv@v3
- name: Print the installed version
  run: echo "Installed uv version is ${{ steps.setup-uv.outputs.uv-version }}"

setup-uv was initially written and published by Kevin Stillhammer before moving under the official Astral organization. You can support Kevin's work in open source on Buy me a coffee or PayPal.

MIT