setup-uv/docs/caching.md

# Caching

This document covers all caching-related configuration options for setup-uv.

## Cache key

The cache key is automatically generated based on:

- **Architecture**: CPU architecture (e.g., `x86_64`, `aarch64`)
- **Platform**: OS platform type (e.g., `unknown-linux-gnu`, `unknown-linux-musl`, `apple-darwin`,
  `pc-windows-msvc`)
- **OS version**: OS name and version (e.g., `ubuntu-22.04`, `macos-14`, `windows-2022`)
- **Python version**: The Python version in use
- **Cache options**: Whether pruning and Python caching are enabled
- **Dependency hash**: Hash of files matching `cache-dependency-glob`
- **Suffix**: Optional `cache-suffix` if provided

Including the OS version ensures that caches are not shared between different OS versions,
preventing binary incompatibility issues when runner images change.

The computed cache key is available as the `cache-key` output:

```yaml
- name: Setup uv
  id: setup-uv
  uses: astral-sh/setup-uv@c771a70e6277c0a99b617c7a806ffedaca235ff9 # v9.0.0
  with:
    enable-cache: true
- name: Print cache key
  run: echo "Cache key: ${{ steps.setup-uv.outputs.cache-key }}"
```

## Enable caching

> [!NOTE]
> The entire uv cache is uploaded to the GitHub Actions cache by default. To reduce the cache size,
> see [Enable cache pruning](#enable-cache-pruning).

If you enable caching, the [uv cache](https://docs.astral.sh/uv/concepts/cache/) will be uploaded to
the GitHub Actions cache. This can speed up runs that reuse the cache by several minutes.
Caching is enabled by default on GitHub-hosted runners.

> [!TIP]
>
> On self-hosted runners this is usually not needed since the cache generated by uv on the runner's
> filesystem is not removed after a run. For more details see [Local cache path](#local-cache-path).

You can optionally define a custom cache key suffix.

```yaml
- name: Enable caching and define a custom cache key suffix
  id: setup-uv
  uses: astral-sh/setup-uv@c771a70e6277c0a99b617c7a806ffedaca235ff9 # v9.0.0
  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:

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

## Cache dependency glob

If you want to control when the GitHub Actions cache is invalidated, specify a glob pattern with the
`cache-dependency-glob` input. The GitHub Actions cache will be invalidated if any file matching the glob pattern
changes. If you use relative paths, they are relative to the working directory.

> [!NOTE]
>
> You can look up supported patterns [here](https://github.com/actions/toolkit/tree/main/packages/glob#patterns)
>
> The default is
> ```yaml
> cache-dependency-glob: |
>   **/*requirements*.txt
>   **/*requirements*.in
>   **/*constraints*.txt
>   **/*constraints*.in
>   **/pyproject.toml
>   **/uv.lock
>   **/*.py.lock
> ```

```yaml
- name: Define a cache dependency glob
  uses: astral-sh/setup-uv@c771a70e6277c0a99b617c7a806ffedaca235ff9 # v9.0.0
  with:
    enable-cache: true
    cache-dependency-glob: "**/pyproject.toml"
```

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

```yaml
- name: Define an absolute cache dependency glob
  uses: astral-sh/setup-uv@c771a70e6277c0a99b617c7a806ffedaca235ff9 # v9.0.0
  with:
    enable-cache: true
    cache-dependency-glob: "/tmp/my-folder/requirements*.txt"
```

```yaml
- name: Never invalidate the cache
  uses: astral-sh/setup-uv@c771a70e6277c0a99b617c7a806ffedaca235ff9 # v9.0.0
  with:
    enable-cache: true
    cache-dependency-glob: ""
```

## Restore cache

Restoring an existing cache can be enabled or disabled with the `restore-cache` input.
By default, the cache will be restored.

```yaml
- name: Don't restore an existing cache
  uses: astral-sh/setup-uv@c771a70e6277c0a99b617c7a806ffedaca235ff9 # v9.0.0
  with:
    enable-cache: true
    restore-cache: false
```

## Save cache

You can also disable saving the cache after the run with the `save-cache` input.
This can be useful to save cache storage when you know you will not use the cache of the run again.
By default, the cache will be saved.

```yaml
- name: Don't save the cache after the run
  uses: astral-sh/setup-uv@c771a70e6277c0a99b617c7a806ffedaca235ff9 # v9.0.0
  with:
    enable-cache: true
    save-cache: false
```

## Local cache path

If caching is enabled, 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\setup-uv-cache` 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.

> [!NOTE]
> If the environment variable `UV_CACHE_DIR` is already set this action will not override it.
> If you configured [cache-dir](https://docs.astral.sh/uv/reference/settings/#cache-dir) in your
> config file then it is also respected and this action will not set `UV_CACHE_DIR`.

> [!NOTE]
> If caching is disabled, you can still use `cache-local-path` so this action sets `UV_CACHE_DIR`
> to your desired path.

```yaml
- name: Define a custom uv cache path
  uses: astral-sh/setup-uv@c771a70e6277c0a99b617c7a806ffedaca235ff9 # v9.0.0
  with:
    cache-local-path: "/path/to/cache"
```

## Enable cache pruning

By default, the entire uv cache is persisted across runs. On GitHub-hosted runners, it's typically
faster to prune the cache before saving it, removing pre-built wheels, but retaining any wheels that
were built from source. The pre-built wheels are then re-downloaded from the registry on each run.
See the [documentation](https://docs.astral.sh/uv/concepts/cache/#caching-in-continuous-integration)
for more information.

If you want to prune the cache before saving it, enable cache pruning with the `prune-cache` input.

```yaml
- name: Prune the cache before saving it
  uses: astral-sh/setup-uv@c771a70e6277c0a99b617c7a806ffedaca235ff9 # v9.0.0
  with:
    enable-cache: true
    prune-cache: true
```

## Cache Python installs

By default, the Python install dir (`uv python dir` / `UV_PYTHON_INSTALL_DIR`) is not cached,
for the same reason that pruning the dependency cache can improve performance on GitHub-hosted
runners.
If you want to cache Python installs along with your dependencies, set the `cache-python` input to `true`.

Note that this only caches Python versions that uv actually installs into `UV_PYTHON_INSTALL_DIR`
(i.e. managed Python installs). If uv uses a system Python, there may be nothing to cache.
To force managed Python installs, set `UV_PYTHON_PREFERENCE=only-managed`.

```yaml
- name: Cache Python installs
  uses: astral-sh/setup-uv@c771a70e6277c0a99b617c7a806ffedaca235ff9 # v9.0.0
  with:
    enable-cache: true
    cache-python: true
```

## Ignore nothing to cache

By default, the action will fail if caching is enabled but there is nothing to upload (the uv cache directory does not exist) with an error like

```console
Error: Cache path /home/runner/.cache/uv does not exist on disk. This likely indicates that there are no dependencies to cache. Consider disabling the cache input if it is not needed.
```

If you want to ignore this, set the `ignore-nothing-to-cache` input to `true`.

```yaml
- name: Ignore nothing to cache
  uses: astral-sh/setup-uv@c771a70e6277c0a99b617c7a806ffedaca235ff9 # v9.0.0
  with:
    enable-cache: true
    ignore-nothing-to-cache: true
```