Simon Willison ha pubblicato una ricetta per usare uvx (il tool runner di uv) nelle GitHub Actions senza che ogni workflow scarichi tutto da PyPI ogni volta. Il trucco sta in due pezzi: imposti una variabile d’ambiente UV_EXCLUDE_NEWER con una data fissa all’inizio del workflow, e usi quella data come parte della chiave di cache. Ogni uvx tool-name risolverà alla versione più recente fino a quella data, e la cache sopravvivrà fra le esecuzioni. Per aggiornare gli strumenti, sposti la data in avanti.

Questo conta se automatizzi workflow Python con GitHub Actions: invece di aspettare ogni volta che il runner scarichi le dipendenze, riusi quello che ha già in cache. Il risultato sono build più veloci e meno traffico verso PyPI. Il pattern è piccolo ma subito applicabile: due righe di config e sai che i tuoi workflow non ripartono da zero a ogni giro.

Se vuoi provarci. Aggiungi UV_EXCLUDE_NEWER: "2026-07-12" (o la data che vuoi) all’inizio del tuo workflow e usa quella variabile nella chiave della cache action. La ricetta completa è documentata con esempio.

Nel dettaglio

Il problema

Quando usi uvx tool-name in un workflow GitHub Actions, di default ogni esecuzione contatta PyPI per scaricare lo strumento e le sue dipendenze. Questo aggiunge latenza a ogni build e spreca banda: se il tool non è cambiato, stai rifacendo lavoro inutile.

La cache delle GitHub Actions esiste proprio per questo, ma serviva un modo per far sì che uvx rispettasse quella cache invece di scaricare sempre tutto di nuovo. Il problema è che uvx di default tenta di risolvere alla versione più recente disponibile, e questo significa che la chiave di cache cambia ogni volta che c’è una nuova release dello strumento, anche se per te quella release non conta.

La soluzione di Willison

La ricetta si basa su UV_EXCLUDE_NEWER, una variabile d’ambiente di uv che dice: «ignora tutto quello che è stato pubblicato dopo questa data». Se imposti UV_EXCLUDE_NEWER: "2026-07-12" all’inizio del workflow, ogni chiamata a uvx risolverà alla versione più recente pubblicata fino al 12 luglio 2026, e quella versione resterà stabile finché non cambi la data.

Usi quella data anche nella chiave della cache action (actions/cache@v4), così GitHub sa che la cache è valida finché la data non cambia. Quando vuoi aggiornare gli strumenti, sposti la data in avanti e la cache si invalida da sola.

Il vantaggio è che hai il controllo esplicito su quando aggiornare, invece di subire ogni nuova release dello strumento senza preavviso. È una forma di pinning morbido: non blocchi una versione specifica, ma blocchi una finestra temporale, e questo basta per tenere la cache coerente.

Perché conta

Se hai workflow che girano spesso (CI su ogni commit, deploy automatici, job schedulati), il tempo risparmiato su ogni esecuzione si accumula. Più importante: elimini una variabile di instabilità. Un workflow che oggi passa e domani fallisce perché una nuova versione di uno strumento ha rotto qualcosa è un problema che questa ricetta previene, perché la data ti dà un punto di controllo esplicito.

C’è anche una issue aperta contro astral-sh/setup-uv che chiede di cambiare il default a favore della cache invece del purge dei wheel. Se quella proposta passa, parte di questo lavoro potrebbe diventare automatico. Nel frattempo, la ricetta di Willison funziona oggi.