Python: come creare e usare un ambiente virtuale per ogni progetto

Un ambiente virtuale è una directory associata a un’installazione di Python che mantiene un proprio insieme di pacchetti. Il modulo standard venv consente di crearne uno e, per impostazione predefinita, isola i suoi pacchetti da quelli installati nell’installazione di base. In questo modo ogni progetto può avere dipendenze indipendenti, invece di condividere necessariamente un’unica raccolta di pacchetti in tutto il computer. Documentazione ufficiale di venv

Immagina due progetti: uno richiede una versione specifica di una libreria e l’altro dipende da una versione diversa. Installare entrambe nello stesso ambiente globale può causare incompatibilità. Con un ambiente distinto per ciascun progetto, ognuno può installare i propri pacchetti senza modificare l’insieme dell’altro. Il vantaggio principale è l’isolamento delle dipendenze, non una separazione completa dal sistema né la garanzia che il progetto funzioni allo stesso modo su qualsiasi computer.

venv è incluso nella libreria standard di Python dalla versione 3.3. L’ambiente viene creato a partire da un’installazione di Python esistente, nota come Python di base, e usa la versione dell’interprete con cui è stato creato. Perciò, creare un ambiente non installa da sé qualsiasi versione di Python richiesta dal progetto: è necessario disporre prima dell’interprete appropriato. Documentazione ufficiale di venv

Prima di creare l’ambiente, apri un terminale e verifica che Python sia disponibile. I nomi dei comandi possono variare in base al sistema e al metodo d’installazione. Su macOS e in molte distribuzioni Linux si prova di solito python3 --version; su Windows, py --version oppure python --version. Se un comando non viene riconosciuto, prova le altre opzioni disponibili e controlla quale interprete richiama ciascuna. Questa guida non presume che tutti i computer abbiano lo stesso comando.

Crea o apri la cartella del progetto ed esegui i comandi da lì. .venv è un nome comune per la directory dell’ambiente: il punto iniziale fa sì che alcuni esploratori la mostrino come nascosta, ma non cambia il funzionamento di Python. La Python Packaging User Guide consiglia inoltre di lavorare in un ambiente virtuale quando si installano pacchetti per un progetto. Python Packaging User Guide

Verifica anche di avere il permesso di scrivere nella cartella e che l’interprete selezionato sia quello che vuoi usare. Se hai più installazioni, il risultato di --version aiuta a individuare una selezione inattesa. L’ambiente eredita la versione di Python usata per crearlo, quindi conviene decidere quale usare prima di installare i pacchetti.

La posizione da cui esegui il comando è importante perché .venv verrà creata nella cartella corrente. Tenerla all’interno del progetto rende più semplice capire a quale progetto appartiene. Se nella cartella esiste già una directory .venv, controllane il contenuto e lo scopo prima di crearne un’altra nello stesso percorso. Scegli l’interprete con attenzione: su un computer con più versioni di Python, il nome del comando da solo non indica quale installazione verrà usata.

Il modulo viene eseguito come modulo Python: -m venv indica all’interprete di richiamare venv, mentre .venv è la directory da creare. Usa il comando adatto alla tua installazione:

• Windows: py -m venv .venv (se il launcher py non è disponibile, prova python -m venv .venv).
• macOS o Linux: python3 -m venv .venv (se python3 non esiste, verifica che python punti all’interprete desiderato).

La documentazione spiega che la creazione genera la directory di destinazione e i file di configurazione; all’interno dell’ambiente, gli eseguibili sono organizzati diversamente a seconda della piattaforma: su Windows si trovano in Scripts, mentre nei sistemi di tipo Unix, come macOS e Linux, si trovano in bin. Documentazione ufficiale di venv In genere, la creazione non stampa una conferma dettagliata; puoi controllare il risultato cercando .venv nella cartella del progetto. Se il comando non riesce, leggi tutto il messaggio prima di riprovare: potrebbe indicare un interprete inesistente, una cartella senza permessi di scrittura oppure un ambiente incompleto. Non dare per scontato che ripetere lo stesso comando risolva la causa del problema. Se la destinazione esiste già, controllala prima di decidere cosa fare, invece di eliminare file senza averne verificato lo scopo. La struttura del comando resta simile tra le piattaforme, ma il comando dell’interprete e l’organizzazione delle directory risultanti possono essere diversi. Conservare la directory dell’ambiente all’interno del progetto rende anche più facili da seguire i successivi comandi di attivazione. Una volta creato, l’ambiente può essere attivato con lo script adatto alla shell che stai usando. La creazione non installa da sola i pacchetti del progetto: l’installazione è un passaggio separato, da eseguire dopo l’attivazione. È utile considerare distintamente la creazione dell’ambiente, l’installazione dei pacchetti e l’esecuzione del progetto. Se non sai quale interprete è stato richiamato, torna al controllo della versione di Python e verifica l’installazione prima di proseguire. In questo modo eviti di creare l’ambiente del progetto con una versione non prevista. Perché la creazione sia riuscita non è necessario che venga stampato un messaggio di conferma specifico: la presenza della directory e dei relativi file è il controllo pratico descritto qui. Un messaggio di errore, invece, va compreso prima di continuare. Controllando la cartella e leggendo il messaggio puoi distinguere un problema di creazione da un successivo problema di attivazione o installazione dei pacchetti. Il nome .venv è convenzionale, non obbligatorio: in questi esempi è il nome scelto per la destinazione, quindi usa lo stesso nome nei comandi successivi. Se scegli un nome diverso, anche i percorsi di attivazione dovranno corrispondere. Gli esempi qui sotto presuppongono che tu abbia mantenuto .venv. Così i comandi restano coerenti dalla creazione all’attivazione e poi alla disattivazione. L’ambiente rimane associato all’installazione di Python usata per crearlo: ecco perché è importante scegliere prima l’interprete. Il comando crea un ambiente locale nella cartella corrente del progetto; non copia l’intero sistema operativo e non sostituisce l’installazione Python di base. Questo limite aiuta a chiarire che cosa significhi “isolato” in questo contesto. Il passo successivo è attivarlo nel terminale da cui intendi lavorare. Se in seguito apri un altro terminale, può essere necessario attivarlo di nuovo anche lì. È un comportamento previsto, non un segnale che l’ambiente sia stato eliminato. I file rimangono in .venv finché non li rimuovi.**

venv offre quindi uno spazio di lavoro locale per i pacchetti di ciascun progetto, creato con l’interprete Python selezionato. La cartella degli eseguibili specifica della piattaforma spiega perché i percorsi di attivazione cambiano, anche se il metodo di creazione è simile. Dopo aver verificato che la directory esista, passa al comando di attivazione adatto al tuo terminale.

Una volta creato, attiva l’ambiente con lo script adatto alla shell che stai usando. Su macOS e Linux, dalla cartella del progetto, esegui source .venv/bin/activate. Su Windows, il comando cambia in base al terminale: in PowerShell usa .venv\Scripts\Activate.ps1; nel Prompt dei comandi usa .venv\Scripts\activate.bat. Quando copi uno dei comandi, non aggiungere uno spazio iniziale.

Dopo l’attivazione, il terminale di solito mostra (.venv) all’inizio del prompt. È un’indicazione pratica, ma non l’unico controllo possibile. Puoi quindi installare una libreria, per esempio con python -m pip install nome-del-pacchetto. Richiamare pip tramite il python attivo aiuta ad associare l’installazione all’interprete selezionato. La documentazione sul packaging descrive il flusso d’installazione con pip all’interno di un ambiente virtuale. Python Packaging User Guide

Esegui il programma con python file.py, sostituendo file.py con il nome effettivo del file. Per confermare quale interprete stai usando, python --version ne mostra la versione; puoi anche controllarne il percorso con python -c "import sys; print(sys.executable)". Installa ed esegui con lo stesso ambiente attivo: così riduci il rischio di installare un pacchetto in un’installazione e avviare il progetto con un’altra.

Il comando di attivazione specifico della shell modifica la sessione del terminale corrente, in modo che comandi come python usino l’interprete dell’ambiente. Per questo è importante attivare l’ambiente nel terminale in cui intendi installare i pacchetti ed eseguire il progetto. Se apri un altro terminale, non presumere che stia già usando lo stesso ambiente: attivalo anche lì e controlla il prompt o il percorso dell’interprete. Questa semplice verifica può aiutare a capire perché un pacchetto sembra mancare anche se il comando d’installazione pare essere riuscito. Quando avvii il programma, usa il nome reale del file e rimani nella cartella del progetto, a meno che il progetto non richieda un’altra directory di lavoro. Gli esempi sono comandi da immettere nel terminale, non testo da aggiungere al file Python.

Per uscire dall’ambiente attivo, digita deactivate e premi Invio. Il comando smette di usare l’ambiente virtuale in quel terminale; non elimina i file di .venv e non disinstalla i pacchetti. Per tornare a lavorare sul progetto, apri un terminale nella sua cartella e ripeti il comando di attivazione corrispondente a Windows, macOS o Linux. Documentazione ufficiale di venv

Se l’attivazione non riesce in PowerShell e compare un messaggio sull’esecuzione di script, non modificare alla cieca le impostazioni di sicurezza del computer. Puoi usare un altro terminale compatibile, come il Prompt dei comandi, e consultare la documentazione di Python per Windows per risolvere la configurazione specifica della tua installazione. Microsoft Learn: Python su Windows Se compare “comando non trovato”, controlla prima di essere nella cartella del progetto, che .venv esista e di aver scritto il percorso adatto alla piattaforma.

Se pip indica che un pacchetto è già installato ma il programma non riesce a trovarlo, verifica sys.executable e il percorso d’installazione: il terminale potrebbe non utilizzare l’ambiente previsto. Se la creazione fallisce perché venv non è disponibile, controlla l’installazione e i componenti Python del sistema; i dettagli dipendono da come è stato installato Python. Non eliminare un’installazione globale come prima misura.

Per individuare un problema, esamina i passaggi separatamente anziché modificare più impostazioni insieme. Controlla prima la cartella e la directory dell’ambiente, poi il percorso dell’interprete e infine ripeti il comando pertinente. L’assenza di (.venv) nel prompt può essere un indizio, ma sys.executable mostra direttamente quale interprete viene richiamato dal comando python corrente. La disattivazione è reversibile: cambia il contesto attivo del terminale, non i file memorizzati nel progetto. Dopo aver individuato il passaggio che non funziona, usa il comando di attivazione adatto al sistema operativo e alla shell, invece di copiare quello previsto per un altro terminale.

Un ambiente virtuale è uno strumento locale di isolamento, non un file di specifica del progetto. Se un’altra persona deve ricostruire l’insieme dei pacchetti, registra le dipendenze in un file gestito dal progetto. Per i progetti semplici che usano pip, un flusso comune consiste nel generare un elenco con python -m pip freeze > requirements.txt e installarlo in un altro ambiente con python -m pip install -r requirements.txt. L’elenco riflette i pacchetti installati e le relative versioni in quel momento; prima di considerarlo una descrizione completa del progetto, verifica che sia adatto alla condivisione e alla manutenzione.

Non includere .venv nel repository: di solito è una directory locale, potenzialmente grande e legata al sistema e all’interprete di origine. Includi invece i file che descrivono il progetto e le sue dipendenze, secondo il flusso di lavoro usato dal team. Quando cloni o copi il progetto su un altro computer, crea un nuovo ambiente con la versione appropriata di Python e installa lì le dipendenze registrate.

L’isolamento di venv ha limiti intenzionali. Non è una macchina virtuale né un container: non sostituisce l’installazione dell’interprete, non copia necessariamente l’intero sistema operativo e non elimina le differenze tra piattaforme. Inoltre, poiché l’installazione di base resta fuori dall’ambiente, un ambiente virtuale non sostituisce le pratiche di sicurezza, aggiornamento e gestione delle versioni. Nell’uso quotidiano, il ciclo è semplice: entrare nel progetto, creare .venv, attivarlo, installare le dipendenze, eseguire il programma e disattivarlo al termine.

L’ambiente in sé non è la registrazione necessaria a un’altra persona per ricreare l’insieme di pacchetti del progetto. Un file delle dipendenze fornisce questo elenco in un formato utilizzabile quando si crea un ambiente nuovo. Il comando freeze elenca pacchetti installati e versioni al momento dell’esecuzione: il risultato va quindi esaminato e mantenuto, invece di presumere che descriva ogni aspetto del progetto. Allo stesso modo, escludere .venv dal repository evita di trattare una directory locale come descrizione condivisa del progetto. Per ricreare l’ambiente su un altro computer, scegli un’installazione Python adeguata e installa lì le dipendenze. In questo modo restano distinti i file del progetto, le registrazioni delle dipendenze e l’ambiente locale usato per eseguirlo. La procedura ribadisce il limite centrale: isolare i pacchetti è utile, ma non rende identici computer o sistemi operativi differenti.