Introduzione
Quando lavori su più progetti Python, il problema più comune non è scrivere il codice, ma mantenere ordinate le dipendenze. Un progetto può richiedere una versione specifica di requests, un altro una libreria diversa, e il sistema operativo potrebbe già avere pacchetti installati globalmente. Se usi tutto nello stesso ambiente, prima o poi ti troverai davanti a conflitti difficili da diagnosticare.
In questo tutorial vedremo un sotto-argomento molto pratico: come creare un ambiente virtuale con virtualenv e installare dipendenze con pip in modo pulito, senza sporcare l’installazione globale di Python. L’obiettivo è imparare un flusso di lavoro semplice ma professionale, adatto sia allo sviluppo locale sia alla collaborazione in team.
Useremo un esempio reale: una piccola utility da riga di comando che scarica dati da un’API pubblica e li salva in JSON. L’esempio ci permetterà di vedere come isolare le dipendenze, installarle correttamente e verificare che il progetto sia riproducibile.
Codice completo
# file: main.py
import json
from pathlib import Path
import requests
API_URL = "https://jsonplaceholder.typicode.com/todos/1"
OUTPUT_FILE = Path("todo.json")
def scarica_dato(url: str) -> dict:
"""Scarica un JSON da un´API e restituisce un dizionario Python."""
response = requests.get(url, timeout=10)
response.raise_for_status()
return response.json()
def salva_json(dati: dict, file_path: Path) -> None:
"""Salva un dizionario in un file JSON leggibile."""
with file_path.open("w", encoding="utf-8") as f:
json.dump(dati, f, ensure_ascii=False, indent=2)
def main() -> None:
dati = scarica_dato(API_URL)
salva_json(dati, OUTPUT_FILE)
print(f"File salvato correttamente in: {OUTPUT_FILE}")
if __name__ == "__main__":
main()
# file: requirements.txt
requests==2.32.3
# Comandi tipici da terminale
# 1. Creare l´ambiente virtuale
python -m virtualenv .venv
# 2. Attivarlo su macOS/Linux
source .venv/bin/activate
# 2b. Attivarlo su Windows PowerShell
# .venvScriptsActivate.ps1
# 3. Installare le dipendenze
pip install -r requirements.txt
# 4. Eseguire lo script
python main.py
# 5. Verificare i pacchetti installati
pip list
# 6. Disattivare l´ambiente
deactivate
Spiegazione
Vediamo il flusso passo per passo.
1. virtualenv crea un ambiente isolato
Il comando virtualenv crea una cartella dedicata, in questo caso .venv, che contiene una copia isolata dell’interprete Python e dei pacchetti installati. Questo significa che tutto ciò che installerai dentro l’ambiente non influenzerà il Python globale del sistema.
Perché è utile? Immagina di lavorare a due progetti:
- Progetto A usa requests 2.31
- Progetto B richiede requests 2.32
Se installi tutto globalmente, una versione può rompere l’altra. Con un ambiente virtuale, invece, ogni progetto ha le sue dipendenze separate.
2. pip installa i pacchetti nell’ambiente attivo
Una volta attivato l’ambiente, il comando pip install non installa più nel sistema, ma dentro .venv. Questo è il punto chiave: pip segue l’ambiente attivo. Se l’ambiente non è attivo, rischi di installare nel posto sbagliato.
Nel nostro esempio, il file requirements.txt contiene:
- requests==2.32.3: versione bloccata per avere installazioni riproducibili
Il vincolo di versione è importante perché evita sorprese. Se una nuova release cambia comportamento, il progetto continuerà a funzionare con la versione testata.
3. Lo script usa una libreria esterna in modo controllato
Il file main.py scarica un JSON da un’API pubblica e lo salva su disco. La libreria esterna requests è usata per effettuare la richiesta HTTP in modo semplice e leggibile.
La funzione scarica_dato fa tre cose corrette:
- usa timeout=10 per evitare richieste bloccate all’infinito
- chiama raise_for_status() per intercettare errori HTTP
- restituisce direttamente il JSON decodificato come dizionario Python
La funzione salva_json usa pathlib, che è più moderno e leggibile rispetto alla gestione manuale delle stringhe di percorso.
4. Perché usare .venv come nome della cartella
Il nome .venv è diventato uno standard de facto. È breve, chiaro e spesso già riconosciuto da editor come VS Code, PyCharm e altri strumenti di sviluppo. Inoltre, il punto iniziale lo rende una cartella nascosta su molti sistemi, evitando di confondere la root del progetto con file tecnici.
5. Attivazione e disattivazione
Quando l’ambiente è attivo, il prompt del terminale cambia spesso per indicarlo. Da quel momento:
- python punta all’interprete dell’ambiente
- pip installa nell’ambiente
- i comandi sono isolati dal resto del sistema
Con deactivate torni all’ambiente globale. È una buona abitudine disattivare l’ambiente quando hai finito, soprattutto se lavori su più progetti durante la giornata.
Best practice
- Usa sempre un ambiente virtuale per ogni progetto: non condividere dipendenze tra progetti diversi.
- Versiona requirements.txt: tienilo nel repository, così il team sa quali pacchetti servono.
- Blocca le versioni importanti: per librerie critiche usa == invece di versioni vaghe come >=.
- Evita di usare pip globalmente: installare pacchetti nel Python di sistema rende difficile la manutenzione.
- Controlla sempre l’ambiente attivo: prima di installare, verifica con which python o where python su Windows.
- Usa timeout e gestione errori nel codice che dipende da rete o servizi esterni.
- Escludi .venv dal repository: l’ambiente si crea localmente, non si committe su Git.
Un consiglio molto utile: se vuoi evitare errori di contesto, usa sempre questi comandi in sequenza:
- crea l’ambiente
- attivalo
- installa le dipendenze
- esegui il progetto
Così riduci quasi a zero i problemi legati a versioni sbagliate o installazioni mischiate.
Riepilogo
In questo tutorial abbiamo visto come usare virtualenv per creare un ambiente isolato e pip per installare dipendenze in modo controllato. L’esempio pratico ha mostrato un piccolo script che scarica dati da un’API e li salva su file JSON, dimostrando un flusso di lavoro realistico e facilmente riutilizzabile.
I punti da ricordare sono questi:
- ogni progetto dovrebbe avere il proprio ambiente virtuale
- pip installa nel contesto dell’ambiente attivo
- requirements.txt aiuta a rendere il progetto riproducibile
- bloccare le versioni evita problemi dovuti ad aggiornamenti imprevisti
Se vuoi lavorare in modo professionale con Python, questo è uno dei primi abitudini da adottare: semplice, efficace e fondamentale.
Approfondisci con risorse ufficiali
- pip documentation: guida ufficiale all’uso di pip e alla gestione dei pacchetti
- virtualenv documentation: documentazione ufficiale per creare ambienti isolati
- Python Packaging User Guide: risorsa fondamentale per comprendere il packaging moderno in Python
- PEP 405: specifica tecnica sugli ambienti virtuali integrati in Python
Se vuoi, nel prossimo passo posso anche mostrarti come integrare questo flusso con Git e .gitignore, oppure come generare automaticamente un requirements.txt partendo da un ambiente già configurato.