Gestire le dipendenze di Python con pip e virtualenv: creare e mantenere un ambiente riproducibile

Introduzione

Quando un progetto Python cresce, il problema più comune non è scrivere codice, ma farlo funzionare sempre nello stesso modo su macchine diverse. Una libreria aggiornata, una versione incompatibile di un pacchetto o un’installazione globale “sporca” possono trasformare un progetto semplice in una fonte continua di errori.

Qui entrano in gioco pip e virtualenv. pip serve a installare e aggiornare i pacchetti Python, mentre virtualenv permette di isolare le dipendenze del progetto in un ambiente separato dal Python del sistema. In questo tutorial vedremo un sotto-argomento molto pratico: come creare un ambiente isolato e mantenere le dipendenze del progetto in modo riproducibile.

Il focus non sarà solo su “come installare pacchetti”, ma su una strategia concreta per evitare conflitti, rendere il progetto facile da condividere e semplificare il lavoro in team.

Codice completo

Nel seguente esempio creiamo un piccolo progetto che usa requests per interrogare un’API pubblica. Vedrai come:

• creare un ambiente virtuale con virtualenv;
• attivarlo;
• installare le dipendenze con pip;
• salvare le dipendenze in un file requirements.txt;
• riprodurre l’ambiente su un’altra macchina.

# file: main.py
import requests

def get_quote():
    url = "https://api.quotable.io/random"
    response = requests.get(url, timeout=10)
    response.raise_for_status()

    data = response.json()
    return f´"{data["content"]}" - {data["author"]}´

if __name__ == "__main__":
    print(get_quote())

# 1) Creazione dell´ambiente virtuale
# Da terminale, nella cartella del progetto:
# python -m virtualenv .venv

# 2) Attivazione dell´ambiente
# Linux/macOS:
# source .venv/bin/activate
#
# Windows (PowerShell):
# .venvScriptsActivate.ps1

# 3) Installazione della dipendenza
# pip install requests

# 4) Verifica delle dipendenze installate
# pip list

# 5) Salvataggio delle dipendenze in requirements.txt
# pip freeze > requirements.txt

# 6) Installazione riproducibile su un´altra macchina
# python -m virtualenv .venv
# source .venv/bin/activate
# pip install -r requirements.txt

# file: requirements.txt
requests==2.32.3
certifi==2024.8.30
charset-normalizer==3.3.2
idna==3.8
urllib3==2.2.2

Spiegazione

Vediamo il flusso in modo più chiaro.

1. Perché usare un ambiente virtuale

Se installi i pacchetti direttamente nel Python di sistema, ogni progetto condivide le stesse librerie. Questo crea problemi quando due progetti richiedono versioni diverse dello stesso pacchetto. Con virtualenv, ogni progetto ha la sua “bolla” isolata.

In pratica, il progetto A può usare requests 2.31 e il progetto B requests 2.32, senza interferenze.

2. Cosa fa pip

pip è il gestore dei pacchetti di Python. Ti permette di installare librerie da PyPI, aggiornarle, rimuoverle e generare un elenco preciso delle dipendenze presenti nell’ambiente.

Comandi utili:

• pip install nome_pacchetto: installa un pacchetto;
• pip uninstall nome_pacchetto: rimuove un pacchetto;
• pip list: mostra i pacchetti installati;
• pip freeze: produce una lista precisa delle versioni installate.

3. Perché usare requirements.txt

Il file requirements.txt è fondamentale per la riproducibilità. Contiene le dipendenze e le loro versioni, così chiunque può ricreare lo stesso ambiente con:

pip install -r requirements.txt

Questo evita il classico problema: “a me funziona”. Se il file è ben mantenuto, il progetto può essere installato in modo coerente su altri computer, server o pipeline CI/CD.

4. Il ruolo di pip freeze

Il comando pip freeze fotografa lo stato attuale dell’ambiente. È utile, ma va usato con attenzione: salva anche dipendenze transitive, cioè quelle installate indirettamente da altri pacchetti.

Per esempio, se installi requests, pip freeze potrebbe includere anche urllib3, idna, certifi e charset-normalizer. Questo non è un errore: serve proprio a bloccare le versioni esatte e rendere l’ambiente ripetibile.

5. Flusso di lavoro consigliato

Un flusso semplice e robusto è questo:

• crea un ambiente virtuale per il progetto;
• attivalo prima di lavorare;
• installa solo le librerie necessarie;
• aggiorna requirements.txt quando aggiungi o modifichi dipendenze;
• non installare pacchetti nel Python globale se non strettamente necessario.

Questo approccio rende il progetto più pulito e riduce i bug dovuti a configurazioni locali differenti.

Best practice

• Usa sempre un ambiente virtuale per progetto: evita di condividere dipendenze tra applicazioni diverse.
• Versiona requirements.txt nel repository: è un file essenziale per il team e per il deploy.
• Pin delle versioni: quando il progetto è stabile, blocca le versioni con == per evitare aggiornamenti improvvisi.
• Evita pip install senza controllo: installare pacchetti “al volo” può introdurre dipendenze non desiderate.
• Separare dipendenze di sviluppo e produzione: se usi strumenti come test runner o formatter, valuta file distinti o una convenzione chiara.
• Ricrea periodicamente l’ambiente: cancellare e ricreare la virtualenv è un buon test di salute del progetto.
• Usa nomi chiari per la virtualenv: ad esempio .venv, così è facile riconoscerla e ignorarla nel controllo versione.

Riepilogo

La combinazione pip + virtualenv è uno dei modi più semplici ed efficaci per gestire le dipendenze in Python. virtualenv isola il progetto, pip installa e controlla i pacchetti, mentre requirements.txt permette di ricreare l’ambiente in modo affidabile.

Se vuoi lavorare in modo professionale, il punto chiave non è solo installare librerie, ma controllare il contesto in cui il codice gira. Un ambiente isolato riduce i conflitti, migliora la collaborazione e rende il progetto più facile da mantenere nel tempo.

In sintesi:

• virtualenv isola;
• pip installa e gestisce;
• requirements.txt documenta e riproduce.

Approfondisci con risorse ufficiali

• pip documentation: documentazione ufficiale di pip, con comandi e opzioni avanzate.
• virtualenv documentation: guida ufficiale per creare ambienti virtuali isolati.
• Python Packaging User Guide: una risorsa completa sul packaging e sulla gestione delle dipendenze in Python.
• PyPI: il repository ufficiale dei pacchetti Python, utile per cercare librerie e verificarne le versioni.

Se vuoi fare un passo ulteriore, il prossimo tema naturale è imparare a distinguere dipendenze dirette e indirette, così da mantenere file di requisiti più puliti e controllabili.