Ambienti virtuali Python (venv)

Un ambiente virtuale è una directory autonoma che contiene una copia privata dell'interprete Python e una cartella site-packages dedicata. I pacchetti installati all'interno di un ambiente virtuale sono completamente isolati dal Python di sistema e da tutti gli altri ambienti presenti sulla macchina — così due progetti possono dipendere da versioni diverse della stessa libreria senza mai entrare in conflitto.

Questo capitolo spiega perché gli ambienti virtuali sono importanti, come crearli e attivarli con il modulo integrato venv, come gestire le dipendenze con pip e il flusso di lavoro quotidiano seguito dalla maggior parte dei progetti Python.

Perché gli ambienti virtuali sono importanti

Immagina di avere due progetti sulla stessa macchina:

• Progetto A richiede requests==2.28.0
• Progetto B richiede requests==2.31.0

Se installi entrambe le versioni nell'ambiente Python globale, pip sovrascrive semplicemente la versione installata precedentemente. Un progetto si romperà. Gli ambienti virtuali risolvono questo problema fornendo a ciascun progetto la propria directory site-packages isolata, così entrambe le versioni coesistono senza interferire tra loro.

Altri vantaggi pratici:

Creare un ambiente virtuale

Python 3.3 e versioni successive includono venv nella libreria standard — non è necessaria alcuna installazione.

python -m venv .venv

Questo crea una directory .venv nella cartella corrente. Il nome .venv è una convenzione comune (il punto iniziale la nasconde sui sistemi Unix-like), ma puoi usare qualsiasi nome — env, venv o anche un nome specifico per il progetto.

Cosa crea venv all'interno di .venv:

.venv/
├── bin/           # Python interpreter + activation scripts (Linux/macOS)
│   ├── activate
│   ├── python -> python3
│   └── pip
├── include/
├── lib/
│   └── python3.x/
│       └── site-packages/   # Installed packages go here
└── pyvenv.cfg               # Records the Python version and base prefix

Su Windows la struttura è leggermente diversa — bin/ diventa Scripts/ e i separatori di percorso sono backslash.

Scegliere una versione specifica di Python

Se hai installato più versioni di Python, passa l'interprete esplicitamente:

python3.11 -m venv .venv

Oppure su Windows:

py -3.11 -m venv .venv

Il file pyvenv.cfg all'interno dell'ambiente registra quale interprete è stato usato, così l'ambiente viene sempre eseguito con quella versione.

Attivare l'ambiente

Creare l'ambiente non lo utilizza automaticamente. Devi attivarlo, operazione che aggiunge la directory bin/ dell'ambiente all'inizio del tuo PATH, in modo che python e pip risolvano nelle copie dell'ambiente.

macOS e Linux:

source .venv/bin/activate

Windows (Prompt dei comandi):

.venv\Scripts\activate.bat

Windows (PowerShell):

.venv\Scripts\Activate.ps1

Dopo l'attivazione, il prompt della shell mostra di solito il nome dell'ambiente tra parentesi:

(.venv) $ python --version
Python 3.12.3
(.venv) $ which python
/your/project/.venv/bin/python

Ogni comando pip install eseguito mentre l'ambiente è attivo installa in .venv/lib/.../site-packages/, mai nel Python di sistema.

Disattivare

Quando hai finito di lavorare sul progetto, o vuoi passare a un ambiente diverso:

deactivate

Il prompt della shell torna alla normalità e python risolve di nuovo nell'interprete di sistema.

Installare pacchetti all'interno di un ambiente virtuale

Con l'ambiente attivo, usa pip normalmente:

pip install requests flask

Verifica che i pacchetti siano stati installati nel posto giusto:

pip show requests

La riga Location: nell'output dovrebbe puntare alla tua directory .venv.

Verificare cosa è installato

pip list

Un ambiente appena creato contiene tipicamente solo pip e setuptools. Tutto il resto che vedi è qualcosa che tu (o un file requirements) hai installato esplicitamente.

Salvare e ripristinare le dipendenze

Esportare un file requirements

Una volta configurato il tuo ambiente, congela le versioni esatte dei pacchetti in modo che chiunque possa riprodurlo:

pip freeze > requirements.txt

Un tipico requirements.txt si presenta così:

certifi==2024.2.2
charset-normalizer==3.3.2
flask==3.0.3
idna==3.6
requests==2.31.0
urllib3==2.2.1

Esegui il commit di requirements.txt nel controllo di versione. Non eseguire il commit della directory .venv stessa — aggiungila a .gitignore.

Ripristinare da un file requirements

Su una nuova macchina o in un clone fresco:

python -m venv .venv
source .venv/bin/activate        # or the Windows equivalent
pip install -r requirements.txt

Questo ricrea un ambiente identico a quello che hai congelato.

Flusso di lavoro standard del progetto

La maggior parte dei progetti Python segue questa sequenza:

# 1. Clone the repository
git clone https://github.com/example/myproject.git
cd myproject

# 2. Create a virtual environment
python -m venv .venv

# 3. Activate it
source .venv/bin/activate

# 4. Install dependencies
pip install -r requirements.txt

# 5. Work on the project ...

# 6. When you add a new package, update the requirements file
pip install newpackage
pip freeze > requirements.txt

Cosa aggiungere a .gitignore

Non eseguire mai il commit della directory dell'ambiente nel controllo di versione — contiene binari compilati, è specifica per la piattaforma e può pesare decine di megabyte. Aggiungi uno di questi pattern al tuo .gitignore:

# Virtual environment
.venv/
venv/
env/

Esegui il commit solo di requirements.txt (o pyproject.toml + requirements.txt). È tutto ciò di cui chiunque ha bisogno per ricostruire l'ambiente da zero.

venv rispetto ad altri strumenti

venv è la soluzione integrata ed è sufficiente per la maggior parte dei casi d'uso. Potresti incontrare anche queste alternative:

Per la maggior parte dei principianti e dei progetti semplici, python -m venv è la scelta giusta — viene fornito con Python e non richiede installazioni aggiuntive.

Errori comuni e soluzioni

"python: command not found" durante la creazione dell'ambiente

Su alcune distribuzioni Linux, Python 3 viene invocato come python3, non python:

python3 -m venv .venv

PowerShell rifiuta di eseguire lo script di attivazione

Per impostazione predefinita, Windows PowerShell blocca gli script non firmati. Abilita l'esecuzione degli script per l'utente corrente:

Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser

Poi esegui di nuovo lo script di attivazione.

Pacchetti installati ma import fallisce

Probabilmente hai dimenticato di attivare l'ambiente. Esegui:

source .venv/bin/activate

Poi riprova l'importazione. Puoi verificare quale Python è attivo con which python (macOS/Linux) o where python (Windows).

L'ambiente fa riferimento a un'installazione Python eliminata

Se aggiorni Python e rimuovi la versione precedente, i link di venv si rompono. Ricrea semplicemente l'ambiente:

rm -rf .venv
python -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt

Tabella di riferimento rapido

Capitoli correlati

• Python pip — la guida completa all'installazione, aggiornamento e rimozione dei pacchetti
• Moduli Python — scopri come funziona il sistema di importazione di Python
• Pacchetti Python — organizza il tuo codice in pacchetti installabili

Esercizi