setup-uv/docs/caching.md

Caching

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

Enable caching

Note

The cache is pruned before it is uploaded to the GitHub Actions cache. This can lead to a small or empty cache. See Disable cache pruning for more details.

If you enable caching, the uv 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.

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@v6
  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"

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 repository root.

Note

You can look up supported patterns here

The default is

cache-dependency-glob: |
  **/*requirements*.txt
  **/*requirements*.in
  **/*constraints*.txt
  **/*constraints*.in
  **/pyproject.toml
  **/uv.lock
  **/*.py.lock

- name: Define a cache dependency glob
  uses: astral-sh/setup-uv@v6
  with:
    enable-cache: true
    cache-dependency-glob: "**/pyproject.toml"

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

- name: Define an absolute cache dependency glob
  uses: astral-sh/setup-uv@v6
  with:
    enable-cache: true
    cache-dependency-glob: "/tmp/my-folder/requirements*.txt"

- name: Never invalidate the cache
  uses: astral-sh/setup-uv@v6
  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.

- name: Don't restore an existing cache
  uses: astral-sh/setup-uv@v6
  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.

- name: Don't save the cache after the run
  uses: astral-sh/setup-uv@v6
  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 in your config file then it is also respected and this action will not set UV_CACHE_DIR.

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

Disable cache pruning

By default, the uv cache is pruned after every run, removing pre-built wheels, but retaining any wheels that were built from source. On GitHub-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 the documentation for more information.

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@v6
  with:
    enable-cache: true
    prune-cache: false

Cache Python installs

By default, the Python install dir (uv python dir / UV_PYTHON_INSTALL_DIR) is not cached, for the same reason that the dependency cache is pruned. If you want to cache Python installs along with your dependencies, set the cache-python input to true.

- name: Cache Python installs
  uses: astral-sh/setup-uv@v6
  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). If you want to ignore this, set the ignore-nothing-to-cache input to true.

- name: Ignore nothing to cache
  uses: astral-sh/setup-uv@v6
  with:
    enable-cache: true
    ignore-nothing-to-cache: true