Article · 2026-07-14 · 3 moments

Using uvx in GitHub Actions in a cache-friendly way

TIL: Using uvx in GitHub Actions in a cache-friendly way I finally found a cache-friendly recipe for using uvx tool-name in GitHub Actions workflows that I like. The trick is setting a UV_EXCLUDE_NEWER: "2026-07-12" environment variable at the start of the workflow and then using that as part of the GitHub Actions cache key. This means any uvx tool-name commands will resolve to the most recent version as-of that date, and you can bust the cache and upgrade the tools by bumping the date ✦ AI generated

Read original ↗

HOST Simon Willison

Claim◆

Setting a UV_EXCLUDE_NEWER environment variable to a fixed date and including that date in the GitHub Actions cache key produces a cache-friendly way to run uvx tool-name in workflows.

Simon Willison describes a recipe he finally settled on for making uvx usage in GitHub Actions cache-friendly: pin a date via UV_EXCLUDE_NEWER and use it in the cache key.

transcript

Simon Willison: I finally found a cache-friendly recipe for using uvx tool-name in GitHub Actions workflows that I like.

explains mechanism · 1provides context · 1

Mechanism◆

Setting UV_EXCLUDE_NEWER to a specific date makes uvx tool-name resolve to the most recent tool version available as of that date, and the cache can be busted and tools upgraded simply by bumping that date later.

The mechanism: pinning UV_EXCLUDE_NEWER fixes dependency resolution to a point-in-time snapshot, and bumping the date later is what triggers a cache-busting upgrade.

transcript

Simon Willison: This means any uvx tool-name commands will resolve to the most recent version as-of that date, and you can bust the cache and upgrade the tools by bumping the date in the future.

extends · 1provides context · 1

Context

The goal of this recipe is to use Python tools in GitHub Actions without every workflow run hitting PyPI to download a fresh copy of the tool and its dependencies.

Willison states the underlying motivation for the technique: avoiding repeated, redundant PyPI downloads on every CI run.

transcript

Simon Willison: My goal here is to use Python tools in GitHub Actions without every run of the workflow hitting PyPI to download a fresh copy of the tool and its dependencies.

provides context · 1

Highlight slides

Cache-Friendly uvx in GitHub Actions✦ from: Setting a UV_EXCLUDE_NEWER environment variable to a fixed date and including that date in the GitHub Actions cache key produces a cache-friendly way to run uvx tool-name in workflows.UV_EXCLUDE_NEWER Pins Tool Resolution✦ from: Setting UV_EXCLUDE_NEWER to a specific date makes uvx tool-name resolve to the most recent tool version available as of that date, and the cache can be busted and tools upgraded simply by bumping that date later.Why It Works✦ from: Setting a UV_EXCLUDE_NEWER environment variable to a fixed date and including that date in the GitHub Actions cache key produces a cache-friendly way to run uvx tool-name in workflows.Upgrading Is Just Bumping the Date✦ from: Setting UV_EXCLUDE_NEWER to a specific date makes uvx tool-name resolve to the most recent tool version available as of that date, and the cache can be busted and tools upgraded simply by bumping that date later.

Related episodes

Article · ByteByteGo Newsletter

Setting a UV_EXCLUDE_NEWER environment variable to a fixed date and including that date in the GitHub Actions cache key produces a cache-friendly way to run uvx tool-name in workflows.

Setting UV_EXCLUDE_NEWER to a specific date makes uvx tool-name resolve to the most recent tool version available as of that date, and the cache can be busted and tools upgraded simply by bumping that date later.

The goal of this recipe is to use Python tools in GitHub Actions without every workflow run hitting PyPI to download a fresh copy of the tool and its dependencies.

A Detailed Guide to API Composition Techniques

Can This Reachy Mini Be My Personal Assistant?

Using Local Coding Agents