Tame Your GitHub Actions: The uvx Caching Trick You Need

If your GitHub Actions are a PyPI-hitting mess, Simon Willison's uvx caching trick might be the stability you crave. But it's not without trade-offs.

The core problem is familiar: every CI run fetches fresh packages, slowing builds and risking version roulette. Willison's solution? Leverage uvx (the CLI for the uv package installer) and GitHub's caching to create a time-locked package snapshot.

Here's the crux:

env:
  UV_EXCLUDE_NEWER: "2026-07-12"

This environment variable, when used in your cache key, tells uvx to ignore any package versions newer than the specified date:

- uses: actions/cache@v3
  with:
    path: ~/.cache/uv
    key: ${{ runner.os }}-uv-${{ env.UV_EXCLUDE_NEWER }}

Now, uvx tool-name commands resolve to a consistent set of package versions, frozen in time. The cache persists until you manually update the date, giving you control over when to accept newer dependencies.

This approach offers clear benefits:

1. Dramatically reduced PyPI traffic
2. Consistent, reproducible builds
3. Controlled, intentional dependency updates

But let's not ignore the elephant in the room: you're deliberately using outdated packages. This could mask compatibility issues with newer releases or, worse, leave you vulnerable to known security issues.

The UV_EXCLUDE_NEWER trick is a band-aid on a deeper wound in the Python ecosystem. It's telling that there's an open issue in the astral-sh/setup-uv repository advocating for caching as the default behavior, rather than constant PyPI purges.

So, should you use this trick? If build speed and stability are critical, and you have a robust process for regularly updating dependencies, it's a powerful tool. But it demands discipline: set reminders to update that date stamp, or you'll find yourself stuck in a 2026 time capsule of Python packages.

Ultimately, Willison's hack exposes a gap in Python's CI tooling. It's a clever workaround, but the fact that we need it highlights the need for more sophisticated, built-in caching strategies in package managers and CI systems. Until then, this environment variable juggling act might just be the stability your workflows need, if you can stomach the trade-offs.