Ambienti virtuali Python: gestire le dipendenze senza caos

Chi programma in Python da qualche mese prima o poi incontra lo stesso problema: un progetto funziona, poi installi una libreria per un altro progetto e il primo smette di funzionare. Oppure un programma che gira perfettamente sul tuo computer fallisce su quello di un collega. Quasi sempre la causa è la stessa: le dipendenze sono installate tutte nello stesso posto, mescolate tra loro. La soluzione si chiama ambiente virtuale.

Il problema delle dipendenze globali

Quando esegui pip install senza precauzioni, la libreria finisce nell'installazione di Python condivisa dall'intero sistema (o dal tuo utente). Immagina due progetti:

• il progetto A usa una libreria nella versione 1.x;
• il progetto B richiede la stessa libreria nella versione 2.x, con modifiche incompatibili.

Una sola installazione globale non può contenere entrambe le versioni. Aggiornando per B, rompi A. Su alcuni sistemi operativi, inoltre, il Python di sistema è usato da strumenti interni: installarci pacchetti a caso può creare problemi difficili da diagnosticare. Per questo le distribuzioni Linux recenti tendono a impedire pip install globale, suggerendo proprio l'uso di ambienti virtuali.

Cos'è un ambiente virtuale

Un ambiente virtuale è una cartella che contiene un interprete Python collegato a quello di base e uno spazio isolato in cui installare le librerie. Ogni progetto ha il suo. Quando l'ambiente è attivo, python e pip puntano a quella cartella, e tutto ciò che installi resta lì.

Non è una macchina virtuale né un container: è un meccanismo leggero, che si crea in pochi secondi e si può cancellare e ricreare senza conseguenze.

Creare e attivare un ambiente con venv

Python include il modulo venv nella libreria standard. Dalla cartella del progetto:

python3 -m venv .venv
source .venv/bin/activate      # Linux e macOS
.venv\Scripts\activate         # Windows (prompt dei comandi)

Dopo l'attivazione, il prompt del terminale mostra di solito il nome dell'ambiente. Da qui in poi:

pip install requests
python script.py
deactivate                     # per uscire dall'ambiente

Il nome .venv è una convenzione diffusa: molti editor lo riconoscono automaticamente e lo propongono come interprete del progetto.

Fissare le dipendenze

Un ambiente virtuale da solo non basta: bisogna anche registrare quali librerie servono, in modo che chiunque possa ricreare lo stesso ambiente. Il metodo più semplice è il file requirements.txt:

pip freeze > requirements.txt
pip install -r requirements.txt

Il primo comando elenca tutti i pacchetti installati con la versione esatta; il secondo li reinstalla altrove. È importante distinguere due livelli:

Per un'applicazione che va in produzione conviene avere le versioni bloccate, così l'ambiente di test e quello reale sono uguali. Per una libreria destinata ad altri progetti, invece, si indicano intervalli di versioni compatibili, per non imporre vincoli troppo rigidi a chi la usa.

pyproject.toml e strumenti moderni

Il file pyproject.toml è oggi il modo standard per descrivere un progetto Python: nome, versione, dipendenze, configurazione degli strumenti. Strumenti come Poetry, PDM o uv lo usano per gestire insieme ambiente virtuale, dipendenze dirette e file di blocco (lock file). Non sono indispensabili per iniziare, ma su progetti con più persone semplificano molto il lavoro, perché separano in modo chiaro ciò che hai dichiarato da ciò che è stato effettivamente risolto.

Il consiglio pratico: impara prima venv e pip, perché sono sempre disponibili e ti fanno capire il meccanismo. Poi adotta uno strumento più evoluto se il progetto lo richiede.

Buone pratiche

1. Un ambiente per progetto, sempre, anche per gli script piccoli che pensi di usare una volta sola.
2. Non mettere la cartella dell'ambiente sotto Git. Aggiungi .venv/ al file .gitignore: l'ambiente si ricrea dai file di dipendenze, non si copia.
3. Annota la versione di Python. Un ambiente creato con una versione non è garantito con un'altra; indicala nel README o in pyproject.toml.
4. Ricrea l'ambiente quando qualcosa è strano. Cancellare la cartella e reinstallare da requirements.txt risolve molti problemi misteriosi e verifica che il file sia davvero completo.
5. Aggiorna con intenzione. Aggiorna le dipendenze in un momento dedicato, esegui i test e poi registra le nuove versioni, invece di ritrovarti aggiornamenti casuali.

Errori frequenti

• Dimenticare di attivare l'ambiente e installare tutto globalmente. Un controllo rapido: which python (o where python su Windows) deve indicare la cartella .venv.
• Usare pip di un Python e python di un altro. Scrivere python -m pip install ... elimina l'ambiguità, perché usa il pip dell'interprete che stai eseguendo.
• Spostare la cartella dell'ambiente. Gli ambienti virtuali contengono percorsi assoluti: se sposti il progetto, è più semplice ricreare l'ambiente.

In sintesi

• Gli ambienti virtuali isolano le dipendenze di ogni progetto ed evitano conflitti tra versioni.
• python3 -m venv .venv e l'attivazione sono tutto ciò che serve per iniziare.
• Registra le dipendenze in requirements.txt o pyproject.toml, mai la cartella dell'ambiente in Git.
• Usa python -m pip per essere certo di installare nell'interprete giusto.
• Quando qualcosa non torna, ricrea l'ambiente da zero: è veloce e rivelatore.