Corso Python / Creare un ambiente virtuale e gestire i pacchetti con pip

Un ambiente virtuale separa i pacchetti Python di un progetto da quelli degli altri progetti. Esegui pip con python -m pip per installare i pacchetti nell’interprete scelto, evitando di confondere installazioni diverse.

Che cosa separa un ambiente virtuale

Due progetti possono richiedere versioni diverse della stessa libreria. Aggiornare un’unica installazione condivisa può far funzionare un progetto e interromperne un altro: una cartella .venv per progetto mantiene separati i pacchetti installati. L’ambiente usa una versione di Python già presente sul computer; non installa automaticamente una versione differente del linguaggio.

Questa separazione non limita l’accesso ai file e non costituisce una barriera di sicurezza: il codice conserva i permessi del tuo utente. La documentazione ufficiale di venv descrive la creazione e il funzionamento degli ambienti.

Nell’editor seleziona lo stesso interprete usato nel terminale, come spiegato nella guida per eseguire Python e controllare il codice in VS Code. Cambiare l’interprete nell’editor e attivare un ambiente in un terminale già aperto sono operazioni distinte: controlla entrambi.

Creare e attivare l’ambiente del progetto

Apri il terminale nella cartella del progetto e scegli l’interprete desiderato. Se esiste già una cartella .venv, verifica a quale progetto appartiene prima di riutilizzarla o ricrearla. Per un progetto nuovo esegui:

python -m venv .venv

Il comando crea la cartella dell’ambiente e, normalmente, vi prepara anche pip. In Windows l’eseguibile si trova in .venv\Scripts\python.exe; su macOS e Ubuntu in .venv/bin/python. Conserva i tuoi file .py fuori da questa cartella.

Per attivare l’ambiente nel terminale Windows PowerShell:

.\.venv\Scripts\Activate.ps1

In una shell Bash o Zsh su macOS e Ubuntu:

source .venv/bin/activate

L’attivazione modifica la ricerca dei comandi nella shell corrente. Il prefisso (.venv) può comparire nel prompt, ma la verifica decisiva è il percorso dell’interprete. Un nuovo terminale potrebbe richiedere una nuova attivazione.

Se PowerShell blocca Activate.ps1, rispetta le regole dell’organizzazione. Puoi eseguire direttamente .\.venv\Scripts\python.exe al posto di python nei comandi seguenti, senza cambiare la politica di esecuzione del computer. Anche su macOS e Ubuntu puoi usare il percorso diretto dell’interprete, senza attivazione.

Installare pacchetti e registrare le versioni

L’esempio usa pandas, una libreria per lavorare con dati tabellari. Verifica il nome del progetto e la fonte di distribuzione prima di installarlo; il nome da passare a pip non coincide sempre con quello usato in import. Dopo avere scelto l’ambiente, esegui questi comandi in ordine:

python -m pip install pandas
python -m pip show pandas
python -m pip freeze > requirements.txt
python -m pip install -r requirements.txt

Il primo comando installa pandas e le dipendenze compatibili. Il secondo mostra versione e percorso di installazione: Location deve appartenere all’ambiente del progetto. Il terzo salva in requirements.txt i pacchetti installati; il quarto li installa o ne verifica la presenza nell’ambiente attualmente selezionato.

Per verificare una ricostruzione reale, crea un secondo ambiente in una cartella diversa e usa il suo interprete per installare lo stesso file. Rieseguire il quarto comando nell’ambiente originale può limitarsi a rispondere Requirement already satisfied, perché i pacchetti ci sono già.

pip freeze descrive ciò che è installato: non calcola un lockfile, non garantisce la stessa installazione su qualsiasi sistema operativo e non verifica da solo gli hash dei file. Conserva anche la versione di Python richiesta dal progetto. La codifica prodotta dalla redirezione può cambiare tra versioni di PowerShell: se pip non legge il file, controllane la codifica e salvalo come testo UTF-8.

Verifica quale Python stai usando e dove si trova il relativo pip:

python -c "import sys; print(sys.executable)"
python -m pip --version

Il primo risultato deve puntare dentro .venv; il secondo deve indicare pip nello stesso ambiente. Se l’attivazione è bloccata, ripeti il controllo con il percorso esplicito dell’interprete: così distingui un problema di ricerca dei comandi da un problema dell’ambiente.

Diagnosticare dipendenze e importazioni

python -c "import sys; print(sys.executable)"
python -m pip --version
python -m pip check

pip check controlla la compatibilità delle dipendenze installate. In assenza di problemi mostra No broken requirements found.; non esegue i test del tuo programma e non garantisce che il pacchetto svolga correttamente qualsiasi operazione.

Se compare ModuleNotFoundError, controlla prima sys.executable, poi installa il pacchetto con il pip di quell’interprete e verifica il nome usato in import. Reinstallare globalmente con permessi di amministratore non corregge un interprete selezionato male. Per errori di certificato o proxy verifica configurazione di rete e certificati attendibili; non disabilitare la verifica TLS per aggirarli.

Per uscire da una sessione attivata esegui deactivate. Per rimuovere un pacchetto usa python -m pip uninstall nome-pacchetto, controllando la conferma e l’ambiente interessato. Prima di ricreare .venv, assicurati che codice, dati e requirements.txt siano fuori dall’ambiente. Ricrea l’ambiente sulla destinazione invece di copiarne semplicemente la cartella da un altro computer.