hynek / setup-cached-uv

Setup uv and Handle Its Cache

Warning

This action is still semi-experimental. I’m happy to hear feedback, though!

This action will download and install the latest version of uv using the official installer and handle its package cache for you.

jobs:
  tests:
    runs-on: ubuntu-latest  # or macOS, or Windows
    steps:
      - uses: hynek/setup-cached-uv@v1

      - run: uv ...

Cache Management

Caution

It’s important to understand that once a cache of a certain name has been created, it will be used in all subsequent jobs within the same workflow and will not be updated.

This means that if you create the cache in the first job that installs only, say, build and twine, and later load the cache again and install more packages, those packages will not be cached for the next run.

A cache also doesn’t expire as long as it has been used in the last 7 days. That does not mean that you’re getting obsolete package versions – just that they’re not cached.

To work around this, setup-cached-uv allows you to add two types of suffixes as inputs to the cache name. This way you can have multiple caches per workflow that contain different sets of packages.

Note that the operating system of the runner is automatically added to the cache name – meaning, without adding suffixes, the names of the caches are uv-Linux, uv-macOS, and uv-Windows.

Optional Inputs

cache-suffix

A static string to append to the cache name. This could, for example, be the name of the job, or the current week number to bust the cache weekly:

      # ...
      - run: echo WEEK=$(date +%V) >>$GITHUB_ENV
        shell: bash

      - uses: ./action
        with:
          cache-suffix: -tests-${{ env.WEEK }}
      # ...

cache-dependency-path

A path to a file whose contents is hashed and appended to the cache name. May contain glob-style patterns and match more than one file. Internally, the GitHub Actions function hashFiles is used to hash the passed path.

Using this with a fully pinned requirements.txt file is the most efficient use of this action because it automatically invalidates the cache.

Examples

Check out our CI to see both inputs in action.

License

The scripts and documentation in this project are released under the MIT License.

setup-cached-uv's Issues

Suggestion: allow pinning uv version and cache it if given

Hi 👋

This action could allow pinning the uv version, to avoid always getting the latest version with a potential breaking change. Something like:

    steps:
      - uses: hynek/setup-cached-uv@v1
        with:
          version: 0.1.31

Two side-effects of this feature to consider:

1. The installation process might need to download the binary directly or use pip install to allow installing a specific version.
2. The installed uv can be cached by using the uv version as part of the key, so next runs with the same uv version can take advantage of the cache instead of downloading/installing again.

Implement `cache-dependency-path` equivalent

I was about to post this issue over in baipp but this might be a better place for it.

The default cache key ${{runner.os}}-uv is not fine-grained enough to work with a heterogeneous CI/CD pipeline with separated build and test steps, because the requirements to build may be very different from the requirements to run and test. since baipp runs first, it will have a cache miss and save the uv cache for the build step, then any subsequent run using setup-cached-uv will have a cache hit, but only primed for the build dependencies and unable to update the cache with additional test dependencies.

Hopefully setup-python will eventually have cache: uv but until then it would be swell if I could add:

- uses: hynek/setup-cached-uv
  with:
    cache-dependency-path: '**/requirements-dev.txt'

which would result in cache keys like:

setup-cached-uv-Linux-22.04-Ubuntu-python-3.12.2-de25a2691d32d697d64ac0f45eb15fbab0ef7c4ca684a123bb5ec913fb6498d0