uv

uv è un package and project manager scritto in Rust per i progetti Python. uv è pensato per essere una soluzione all-in-one ovvero essere l'unico strumento da utilizzare per:

scaricare pacchetti da PyPi (sostituisce pip)
gestire ambienti virtuali (sostituisce venv)
installare (copie) di Python stesso (sostituisce pyenv)
gestire progetti e le loro dipendenze (sostituisce pip-tools, poetry, etc...)
utilizzare ambienti e tools di test e di sviluppo (sostituisce pipx, etc... )
creare pacchetti distribuibili (sostituisce poetry, etc...)
pubblicare pacchetti su PyPi (sostituisce twine)

In buona sostanza, uv è l'unico strumento che dovremo imparare ad utilizzare per fare alcune o tutte queste cose. E non mi sembra neanche uno strumento difficile da utilizzare

Installare uv

Su Windows puoi utilizzare l'installer di rete. Ti basta aprire il terminale e copiaincollare:

Comando powershell su Windows

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

Analoga cosa su MacOS, apri il terminale ed esegui:

Comando da terminale su MacOS e Linux

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

Su Linux puoi decidere se utilizzare lo stesso comando disponibile per MacOS oppure affidarti al pacchetto disponibile nella tua distro!!!

Per aggiornare uv, una volta che lo hai installato, ti basta ricorrere al suo sistema di auto-aggiornamento. Sul terminale di qualunque OS, digita:

uv self update

Creare un progetto

Comando semplicissimo:

uv init --opzione nomeProgetto

dove opzione è una delle seguenti (ho citato solo le 3 più comuni):

Tipo	Opzione	Build System	Struttura	Punto di accesso	Distribuzione	Casi d'uso
Applicazione	--app (default)	no	flat	`main.py`	non intesa	Web apps, script
Libreria	--lib	sì	`src` layout	(nessuno)	PyPi	Librerie riutilizzabili
Pacchetto	--package	sì	`src` layout	console script	app installabili, PyPi	CLI, GUI apps

Le app hanno struttura piatta ovvero creando una applicazione di nome provaApp si ottiene la seguente struttura:

provaApp
├── .git
├── .gitignore
├── main.py
├── pyproject.toml
├── .python-version
└── README.md

Librerie e pacchetti hanno una struttura con la cartella dei sorgenti, quindi creando un pacchetto di nome provaPack si ottiene la seguente struttura:

provaPack
├── .git
├── .gitignore
├── pyproject.toml
├── .python-version
├── README.md
└── src
    └── provapack
        └── __init__.py

Notate che in entrambi sono già presenti un repository git e un file per il controllo della versione Python in uso.

Gestire un ambiente virtuale

La gestione degli ambienti virtuali con uv è estremamente semplice e, nella maggior parte dei casi, completamente automatica!

Quando crei un nuovo progetto con uv init, l'ambiente virtuale non viene creato immediatamente. Verrà creato automaticamente al primo comando che ne ha bisogno, ad esempio:

cd provaPack
uv add requests

Questo comando:

Crea automaticamente l'ambiente virtuale nella cartella .venv
Installa il pacchetto requests e le sue dipendenze
Aggiorna il file pyproject.toml con la nuova dipendenza

Sincronizzare l'ambiente

Se hai scaricato un progetto già esistente (ad esempio da Git) e vuoi ricreare l'ambiente virtuale con tutte le dipendenze, usa:

uv sync

Questo comando crea l'ambiente virtuale dove installa la versione di Python indicata nel file .python-version, installa tutti i pacchetti necessari, indicati nel file pyproject.toml nelle stesse versioni indicate nel file uv.lock e rende il sistema pronto all'esecuzione identica del codice in qualunque ambiente!

Eseguire script nell'ambiente virtuale

Per eseguire il tuo codice Python usando l'ambiente virtuale del progetto:

uv run main.py

oppure, se hai creato un pacchetto (come probabilmente ti ho suggerito):

uv run nomePacchetto

Il comando uv run si occupa automaticamente di:

eseguire uv sync (vedi sopra)
attivare l'ambiente virtuale
Eseguire il comando
Disattivare l'ambiente al termine

Gestire le dipendenze

uv è potente, ma semplice da usare anche per la gestione delle dipendenze. Immagina (ad esempio) che il pacchetto che stai creando dipenda dalla libreria nome-pacchetto. Per aggiungerla come dipendenza al progetto:

uv add nome-pacchetto

Clamorosamente, il comando per rimuoverla invece è:

uv remove nome-pacchetto

Per vedere tutti i pacchetti installati:

uv pip list

Ricorda che uv non andrà ad installare il pacchetto nel tuo Python ma nel suo ambiente virtuale! In questo modo tutto sarà più riproducibile in qualunque ambiente tu lavori (casa, scuola, lavoro, PC con Windows, Mac, Linux, etc...)

Lock file

uv crea automaticamente un file uv.lock che contiene le versioni esatte di tutti i pacchetti installati. Questo garantisce che chiunque scarichi il progetto avrà esattamente le stesse versioni dei pacchetti, evitando problemi di compatibilità.

uv.lock

Aggiungi il file uv.lock al controllo di versione (Git) per condividere l'ambiente esatto con tutti quelli che collaborano con te e con tutti quelli che vogliono provare il tuo progetto!

Installare Python (per il tuo progetto)

Sì... è vero... non lo avevo ancora detto. Fino a qui potresti anche non avere Python installato nel tuo computer!

uv può scaricare e gestire versioni di Python in modo completamente indipendente dal sistema operativo. Ogni progetto può usare la sua versione specifica di Python, senza conflitti con altri progetti o con l'installazione di sistema.

Per indicare ad uv quale versione python vuoi utilizzare nel tuo progetto, puoi farlo in due modi:

o specificando in fase di creazione del progetto:

uv init --python 3.13 mio-progetto

oppure, in seguito alla creazione, con il comando:

uv python pin 3.13

I comandi indicati aggiornano semplicemente il file .python-version e da quel momento tutti i comandi uv run useranno Python 3.13.

Il file .python-version

Il file .python-version contiene semplicemente la versione di Python richiesta dal progetto, ad esempio:

3.12

uv legge automaticamente questo file e usa la versione corretta. Se la versione non è installata, uv la scarica automaticamente al primo utilizzo!

Per vedere tutte le versioni di Python che puoi installare:

uv python list --all-versions

Potresti infine decidere di voler provare ad eseguire uno script con una versione diversa di Python. Questa cosa, tecnicamente complicatissima fino ad ora, diventa praticamente banale con uv. Se vuoi provare il funzionamento del tuo script con la nuova fiammante 3.14:

uv run --python 3.14 python script.py