Ambienti virtuali Python con venv: cosa sono e come usarli

Appena si inizia a usare Python seriamente, si incontra un problema: ogni progetto ha bisogno delle sue librerie, a volte in versioni diverse. Uno script vuole una certa versione di una libreria, un altro progetto ne vuole una più recente, e installare tutto nello stesso posto porta prima o poi a conflitti difficili da capire.

La soluzione si chiama ambiente virtuale. In questa guida vediamo cos'è, perché conviene usarlo sempre e come gestirlo con venv, lo strumento incluso in Python, sia su Windows sia su Linux.

Cos'è un ambiente virtuale

Un ambiente virtuale è una cartella che contiene una copia isolata di Python con le sue librerie. Quando l'ambiente è attivo, tutto quello che installi finisce lì dentro, e non nel Python generale del computer.

Puoi immaginarlo come una cassetta degli attrezzi dedicata a un singolo lavoro: ogni progetto ha la sua, con gli strumenti di cui ha bisogno, e le cassette non si mescolano tra loro.

I vantaggi concreti sono tre:

• Niente conflitti: due progetti possono usare versioni diverse della stessa libreria.
• Il sistema resta pulito: su Linux, in particolare, non rischi di danneggiare il Python usato dal sistema operativo.
• Il progetto è riproducibile: puoi ricreare lo stesso ambiente su un altro computer o su un server con un solo comando.

Prima di iniziare

Ti serve Python già installato. Su Ubuntu e Debian assicurati di avere anche il modulo venv, che non sempre è presente:

sudo apt install python3-venv

Su Windows, se hai installato Python con il Python Install Manager, venv è già incluso.

Creare un ambiente virtuale

Apri il terminale nella cartella del tuo progetto e digita:

# Windows
python -m venv .venv

# Linux e macOS
python3 -m venv .venv

Il comando crea una cartella chiamata .venv con dentro tutto il necessario. Il nome è una convenzione molto diffusa: il punto iniziale la rende «nascosta» su Linux e la maggior parte degli editor la riconosce automaticamente. Puoi chiamarla come preferisci, ma .venv è la scelta più comoda.

Su Windows, se hai più versioni di Python installate, puoi scegliere con quale creare l'ambiente:

py -V:3.14 -m venv .venv

L'ambiente userà sempre la versione con cui è stato creato.

Attivare l'ambiente

Creare l'ambiente non basta: bisogna attivarlo ogni volta che si apre un nuovo terminale per lavorare al progetto. Il comando cambia a seconda del sistema:

# Windows, Prompt dei comandi
.venv\Scripts\activate

# Windows, PowerShell
.venv\Scripts\Activate.ps1

# Linux e macOS
source .venv/bin/activate

Quando l'ambiente è attivo, all'inizio della riga del terminale compare il suo nome tra parentesi, per esempio (.venv). È il segnale che stai lavorando dentro l'ambiente.

Se PowerShell blocca lo script di attivazione con un errore sui criteri di esecuzione, consenti l'esecuzione degli script locali per il tuo utente con questo comando, da eseguire una sola volta:

Set-ExecutionPolicy -Scope CurrentUser RemoteSigned

Installare le librerie

Con l'ambiente attivo, le librerie si installano con pip, il gestore di pacchetti di Python:

python -m pip install requests

Perché python -m pip e non semplicemente pip? Perché così hai la certezza che pip installi la libreria proprio nel Python che stai usando. Con il comando pip da solo, se l'ambiente non è attivo o ci sono più versioni installate, la libreria potrebbe finire nel posto sbagliato. È una piccola abitudine che evita molti problemi.

Per vedere le librerie installate nell'ambiente:

python -m pip list

Salvare e ricreare le dipendenze con requirements.txt

Le librerie usate da un progetto si chiamano dipendenze. Per salvarne l'elenco, con le versioni esatte, si usa un file chiamato requirements.txt:

python -m pip freeze > requirements.txt

Su un altro computer, o sul server, basta creare un nuovo ambiente virtuale, attivarlo e installare tutto con un solo comando:

python -m pip install -r requirements.txt

Il file requirements.txt va conservato insieme al codice del progetto. La cartella .venv, invece, non va copiata né inserita in Git: contiene percorsi legati al tuo computer e si ricrea in pochi secondi. Se usi Git, aggiungi questa riga al file .gitignore:

.venv/

Disattivare ed eliminare un ambiente

Per uscire dall'ambiente virtuale basta digitare:

deactivate

Per eliminarlo del tutto, cancella semplicemente la cartella .venv. Non c'è nessuna disinstallazione da fare: tutto quello che conteneva era lì dentro.

Questo è utile anche quando vuoi cambiare versione di Python a un progetto: elimina la cartella, ricrea l'ambiente con la nuova versione e reinstalla le dipendenze da requirements.txt.

Usare l'ambiente con Visual Studio Code

Se usi Visual Studio Code con l'estensione Python, l'editor di solito riconosce da solo la cartella .venv. Se non succede, apri la palette dei comandi con Ctrl+Shift+P, cerca Python: Select Interpreter e scegli l'interprete che si trova dentro .venv. Da quel momento, anche il terminale integrato attiverà l'ambiente automaticamente.

Errori comuni e soluzioni

• «ModuleNotFoundError: No module named …»: quasi sempre l'ambiente non è attivo, oppure la libreria è stata installata in un altro Python. Attiva l'ambiente e reinstalla la libreria con python -m pip install.
• «error: externally-managed-environment» su Linux: stai cercando di installare una libreria nel Python di sistema. Crea e attiva un ambiente virtuale e ripeti l'installazione lì dentro.
• «The virtual environment was not created successfully because ensurepip is not available» su Ubuntu o Debian: manca il pacchetto python3-venv. Installalo con sudo apt install python3-venv, elimina la cartella .venv incompleta e ricrea l'ambiente.
• L'ambiente non funziona più dopo aver spostato o rinominato la cartella del progetto: gli ambienti virtuali contengono percorsi assoluti e non sopportano gli spostamenti. Eliminalo e ricrealo.
• Errore «Microsoft Visual C++ 14.0 or greater is required» durante l'installazione di una libreria: di solito l'ambiente è stato creato con una versione di Python troppo recente per quella libreria. Abbiamo dedicato un articolo a questo errore.

Uno sguardo agli strumenti alternativi

Oltre a venv esistono strumenti più completi, come uv o Poetry, che gestiscono in un colpo solo ambienti, dipendenze e versioni di Python. Sono molto apprezzati nei progetti più grandi. Per iniziare, però, venv è la scelta migliore: è già incluso in Python, funziona ovunque e i concetti che hai imparato qui valgono anche per gli altri strumenti.

Riepilogo

Il flusso di lavoro di ogni progetto Python si riduce a pochi comandi:

• Una volta: python -m venv .venv nella cartella del progetto.
• Ogni volta che lavori al progetto: attiva l'ambiente.
• Per aggiungere librerie: python -m pip install nome, poi aggiorna requirements.txt.
• Su un altro computer: crea l'ambiente, attivalo e lancia python -m pip install -r requirements.txt.

Fonti ufficiali

• venv — Creation of virtual environments – documentazione ufficiale di Python
• Install packages in a virtual environment using pip and venv – Python Packaging User Guide
• pip User Guide – documentazione ufficiale di pip
• Python environments in VS Code – documentazione di Visual Studio Code