Introduzione
Quando un progetto Python cresce, il problema non è solo installare le librerie, ma soprattutto installare le versioni giuste. Una dipendenza aggiornata in modo automatico può introdurre bug, cambiare il comportamento di una funzione o rompere completamente il progetto. Per questo, oltre a creare un ambiente isolato con virtualenv, è fondamentale sapere come bloccare le versioni dei pacchetti usando pip.
In questo tutorial vedremo un sotto-argomento molto pratico: come congelare le dipendenze di un progetto in un file requirements.txt e reinstallarle in modo riproducibile. È una tecnica semplice, ma ancora oggi è una delle più utili per lavorare in team, distribuire codice e preparare ambienti di sviluppo o produzione coerenti.
L’obiettivo è evitare il classico problema: “sul mio PC funziona, sul tuo no”. Con un ambiente virtuale e un elenco preciso delle dipendenze, puoi ricreare lo stesso setup su qualunque macchina.
Codice completo
# Creazione ambiente virtuale:
# python -m venv .venv
# Attivazione su Linux/macOS:
# source .venv/bin/activate
# Attivazione su Windows:
# .venvScriptsactivate
# Installazione di alcune librerie
# pip install requests pandas
# Generazione del file requirements.txt con versioni bloccate
# pip freeze > requirements.txt
# Installazione riproducibile su un altro ambiente:
# pip install -r requirements.txt
# Esempio di script Python che usa le dipendenze installate
import requests
import pandas as pd
def scarica_dati(url: str) -> dict:
"""Scarica JSON da un endpoint HTTP."""
risposta = requests.get(url, timeout=10)
risposta.raise_for_status()
return risposta.json()
def crea_tabella(dati: list[dict]) -> pd.DataFrame:
"""Converte una lista di dizionari in un DataFrame."""
return pd.DataFrame(dati)
def main() -> None:
url = "https://jsonplaceholder.typicode.com/users"
utenti = scarica_dati(url)
tabella = crea_tabella(utenti)
# Mostra le prime righe e salva un CSV
print(tabella.head())
tabella.to_csv("utenti.csv", index=False)
if __name__ == "__main__":
main()
Spiegazione
Vediamo il flusso completo, passo per passo.
1. Creare un ambiente virtuale
Il comando python -m venv .venv crea una cartella dedicata all’ambiente isolato. Dentro questa cartella ci sono una copia dell’interprete Python e gli strumenti necessari a gestire i pacchetti senza toccare l’installazione globale del sistema.
Questo è importante perché ogni progetto dovrebbe avere il proprio ambiente. In questo modo puoi usare versioni diverse della stessa libreria in progetti diversi, senza conflitti.
2. Installare i pacchetti con pip
Dopo aver attivato l’ambiente, puoi installare le librerie con pip install. Nell’esempio abbiamo usato requests per fare richieste HTTP e pandas per manipolare dati tabellari.
Questa fase è utile durante lo sviluppo, ma da sola non basta: se domani esce una nuova versione di pandas, un altro sviluppatore potrebbe installarla senza volerlo e ottenere risultati diversi.
3. Congelare le dipendenze con pip freeze
Il comando pip freeze > requirements.txt salva in un file tutte le dipendenze installate, con le versioni esatte. Per esempio, il file potrebbe contenere righe come queste:
requests==2.32.3
pandas==2.2.2
numpy==2.0.1
Questa operazione è il cuore della riproducibilità. Non stai dicendo solo “mi serve requests”, ma “mi serve proprio la versione 2.32.3 di requests”.
4. Ricreare l’ambiente su un’altra macchina
Quando un collega clona il progetto, oppure quando devi deployare su un server, basta creare un nuovo ambiente virtuale e poi eseguire:
pip install -r requirements.txtpip leggerà il file e installerà esattamente le versioni indicate. Questo riduce molto il rischio di incompatibilità.
5. Usare le dipendenze nel codice
Nello script di esempio, la funzione scarica_dati usa requests per ottenere un JSON da un endpoint pubblico. La funzione crea_tabella converte i dati in un DataFrame pandas e poi li salva in un file CSV.
Il punto importante non è solo il codice in sé, ma il fatto che il progetto dipende da librerie esterne. Se non controlli le versioni, il comportamento può cambiare nel tempo. Con requirements.txt, invece, hai una fotografia precisa dell’ambiente.
Best practice
- Usa sempre un ambiente virtuale per ogni progetto, anche piccolo.
- Blocca le versioni quando il progetto è pronto per essere condiviso o distribuito.
- Non installare pacchetti globalmente se puoi evitarlo: riduci il rischio di conflitti tra progetti.
- Controlla requirements.txt nel versionamento se il progetto è collaborativo, così tutti lavorano con le stesse dipendenze.
- Aggiorna con cautela: prima di cambiare versione a una libreria, esegui test automatici o almeno una verifica manuale delle funzionalità critiche.
- Separa dipendenze di sviluppo e produzione quando il progetto cresce. Strumenti come pip permettono di gestire file diversi o di organizzare meglio le dipendenze.
- Evita di usare pip freeze in modo cieco in progetti grandi: può includere anche dipendenze indirette che non hai installato esplicitamente. È utile, ma va usato con consapevolezza.
Riepilogo
La combinazione di pip e virtualenv è una base solida per gestire progetti Python in modo professionale. Il punto chiave di questo tutorial è che non basta installare librerie: bisogna anche salvare le versioni esatte e poterle reinstallare in qualsiasi momento.
Il flusso consigliato è semplice:
- crei un ambiente virtuale;
- installi le dipendenze con pip;
- congeli le versioni in requirements.txt;
- ricrei l’ambiente con pip install -r requirements.txt.
Questa pratica migliora la collaborazione, rende il progetto più stabile e ti aiuta a diagnosticare i problemi più velocemente. È una di quelle abitudini che, una volta adottate, fanno davvero la differenza nel lavoro quotidiano.
Approfondisci con risorse ufficiali
- pip user guide – documentazione ufficiale di pip: installazione, freeze e requirements file.
- Python venv documentation – guida ufficiale al modulo standard per gli ambienti virtuali.
- Python Packaging User Guide – risorsa completa per comprendere packaging, dipendenze e distribuzione.
- PEP 508 – specifica per i requisiti delle dipendenze e i marker ambientali.