Come configurare un progetto Python veloce e riproducibile con uv

Quando indirizzi un agente di coding IA come Claude Code o Codex verso un progetto Python, metà degli attriti non ha nulla a che fare con il modello. Derivano dall'ambiente: pacchetti mancanti, la versione sbagliata di Python, un virtualenv che l'agente ha dimenticato di attivare o un collega per cui "sul mio computer funziona". La soluzione è un progetto che sia riproducibile per impostazione predefinita, e oggi il modo più rapido per ottenerne uno è uv, il toolchain Python basato su Rust di Astral.

uv sostituisce pip, venv, pip-tools e pyenv con un unico comando veloce, e scrive un lockfile in modo che lo stesso identico albero delle dipendenze venga installato ovunque. Questa guida ti porta da zero a un progetto bloccato ed eseguibile in pochi minuti.

Perché l'ambiente è importante per un agente

Un agente IA esegue comandi nella tua shell e legge gli errori che ne ritornano. Se il tuo progetto non ha dipendenze dichiarate né una versione di Python fissata, l'agente deve indovinare — e una supposizione sbagliata lo trascina in un vicolo cieco fatto di installazioni globali di pacchetti o di modifiche all'interprete sbagliato. Un progetto con un pyproject.toml e un uv.lock offre all'agente un'unica fonte di verità: può eseguire uv sync, ottenere i pacchetti giusti e andare avanti. Tu spendi il tuo tempo di revisione sulla logica, non sull'archeologia dell'ambiente.

Installare uv

Su macOS o Linux:

curl -LsSf https://astral.sh/uv/install.sh | sh

Su Windows (PowerShell):

powershell -c "irm https://astral.sh/uv/install.ps1 | iex"

uv è un singolo binario autonomo, quindi non c'è nient'altro da configurare.

Avviare un progetto in un solo comando

uv init weather-cli
cd weather-cli

Questo genera l'impalcatura di un progetto funzionante: un pyproject.toml per metadati e dipendenze, un file .python-version, un main.py iniziale, un README.md e un .gitignore. Non crei né attivi un virtualenv a mano — uv gestisce un .venv per te nel momento in cui ne hai bisogno.

Aggiungere dipendenze (e perché il lockfile è importante)

uv add requests

Questo fa tre cose contemporaneamente: registra requests in pyproject.toml, risolve l'intero albero delle dipendenze e scrive uv.lock con versioni esatte e fissate, valide su tutte le piattaforme. Puoi anche fissare la versione al momento dell'aggiunta:

uv add 'requests==2.31.0'

Fai il commit di uv.lock su Git. È la differenza tra "installa l'ultima versione di requests" (che cambia nel tempo) e "installa l'albero esatto che abbiamo testato". Quando il tuo agente — o la tua CI, o un nuovo collega — esegue uv sync, ottengono un ambiente identico byte per byte.

Eseguire il codice senza attivare nulla

uv run main.py

uv run si assicura che l'ambiente sia sincronizzato, poi esegue al suo interno — niente balletto di source .venv/bin/activate. Questo è particolarmente importante per gli agenti: ogni chiamata a uno strumento è spesso una nuova shell, quindi "attiva e poi esegui" si rompe di frequente, mentre un singolo uv run funziona sempre. Puoi avvolgere qualsiasi comando:

uv run -- pytest -q
uv run -- flask run -p 3000

Fissare una versione di Python così che agente e CI siano d'accordo

uv python pin 3.12

Questo scrive la versione nel file .python-version, e uv scaricherà e userà automaticamente quell'interprete — senza bisogno di un Python di sistema. Ora la versione su cui sviluppi è la versione che il tuo agente, i tuoi colleghi e la tua CI usano tutti.

Un breve esempio pratico

Supponiamo che tu chieda a un agente di "aggiungere un comando che recuperi il meteo di oggi". Con uv già in posizione, l'intero ciclo è pulito:

uv init weather-cli && cd weather-cli
uv add requests
uv python pin 3.12
# l'agente modifica main.py per chiamare un'API...
uv run main.py

L'agente non deve mai ragionare su quale interprete sia attivo o se requests sia installato — quei fatti sono dichiarati in file che può leggere. Se introduce una nuova dipendenza, esegue uv add e il lockfile si aggiorna. Se qualcosa si rompe nella CI, uv sync riproduce l'ambiente esatto in locale così puoi farne il debug.

Dove sta andando uv

uv e i suoi strumenti fratelli ruff (linter/formattatore) e ty (type checker) sono ampiamente adottati — solo uv registra ben oltre 100 milioni di download al mese. A marzo 2026, OpenAI ha concordato l'acquisizione di Astral, l'azienda che li sviluppa, per integrare il toolchain nella sua piattaforma Codex, impegnandosi al contempo a mantenere open source gli strumenti con licenza MIT (OpenAI, Simon Willison). Per ora la conclusione pratica resta invariata: uv è il percorso più veloce verso un progetto Python su cui il tuo agente IA può costruire senza tirare a indovinare.

Riferimento rapido

Attività	Comando
Creare un progetto	uv init <name>
Aggiungere una dipendenza	uv add <package>
Fissare Python	uv python pin 3.12
Eseguire codice	uv run <file or command>
Riprodurre l'ambiente	uv sync
Aggiornare il lockfile	uv lock --upgrade-package <pkg>