Cache‑friendly uvx usage in GitHub Actions with UV_EXCLUDE_NEWER
Set UV_EXCLUDE_NEWER to a date and use it in the cache key so uvx resolves to the most recent version as‑of that date.
Add UV_EXCLUDE_NEWER and cache key logic to your GitHub Actions workflow.
Summary
Using uvx in GitHub Actions can be made cache‑friendly by setting an environment variable UV_EXCLUDE_NEWER to a specific date. The date is incorporated into the cache key, ensuring that uvx resolves to the most recent tool version as of that date. Bumping the date in the future busts the cache and upgrades the tools without downloading from PyPI on each run. This approach keeps workflow runs fast and deterministic. The author also requested that the astral‑sh/setup‑uv repository switch its default to cache rather than purge wheels from PyPI. The technique works for any Python tool invoked via uvx. It eliminates repeated downloads and reduces build times. The method is especially useful for CI pipelines that rely on up‑to‑date tool versions.
Key changes
- Set UV_EXCLUDE_NEWER to a specific date
- Use the date in the cache key to lock uvx to that version
- Bumping the date busts the cache and upgrades tools
- Avoids downloading from PyPI on each run
- Reduces workflow run time