Ambienti virtuali in Python: venv, attivazione e requirements.txt

Il problema che risolvono gli ambienti virtuali

Installi Python, esegui pip install requests e il pacchetto finisce in un unico posto globale. Per un progetto funziona. Al terzo progetto comincia a fare male:

• Il progetto A richiede django==3.2. Il progetto B richiede django==5.0. Solo uno dei due può avere la sua versione installata a livello globale.
• Vuoi provare una nuova libreria ma non vuoi che sporchi tutti gli altri progetti sul tuo computer.
• Chi collabora con te clona il tuo repository e non ha idea di quali versioni di quali pacchetti usassi davvero.

Un ambiente virtuale è la soluzione. È una cartella autonoma che contiene un interprete Python e una sua cartella per le librerie installate. Quando l'ambiente è attivo, python e pip nel tuo terminale puntano dentro quella cartella invece che al Python di sistema. I pacchetti installati lì restano lì.

Crearne uno con venv

venv è incluso in Python 3: non c'è niente da installare. Dalla cartella del tuo progetto:

python3 -m venv .venv

Questo crea una cartella .venv/ accanto al tuo codice. Il nome .venv è una convenzione quasi universale; il punto iniziale la nasconde dalla maggior parte degli elenchi di file, e gli editor come VS Code la rilevano automaticamente.

Al termine del comando, la cartella contiene un'installazione completa di Python (decine di megabyte, ed è normale) e un suo pip.

Attivare l'ambiente

L'attivazione riscrive il PATH della tua shell in modo che python e pip corrispondano a quelli dentro .venv/. Il comando dipende dalla piattaforma:

# macOS / Linux
source .venv/bin/activate

# Windows (Command Prompt)
.venv\Scripts\activate.bat

# Windows (PowerShell)
.venv\Scripts\Activate.ps1

Mentre l'ambiente è attivo, il prompt riceve il prefisso (.venv): un promemoria visivo. Qualsiasi pip install che esegui ora riguarda solo questo progetto.

Quando hai finito per oggi, deactivate ripristina lo stato precedente:

deactivate

Non serve disattivarlo prima di chiudere il terminale: uscire dalla shell ha lo stesso effetto.

Installare pacchetti

Con l'ambiente attivo, installa ciò che ti serve:

pip install requests
pip install "pandas>=2.0"
pip install --upgrade requests

Controlla cosa è installato con pip list. Rimuovi qualcosa con pip uninstall requests.

I pacchetti installati si trovano in .venv/lib/pythonX.Y/site-packages/. Non modificarli mai a mano: è pip a gestire quella cartella.

Fissare le dipendenze con requirements.txt

Il tuo progetto è riproducibile solo se altri possono installare le stesse versioni che hai usato tu. Il modo più semplice per registrarle è requirements.txt:

pip freeze > requirements.txt

pip freeze stampa ogni pacchetto installato con la sua versione esatta. Fai il commit del file in git.

Quando chi collabora con te (o il te del futuro su un nuovo computer) clona il repository:

python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt

Tre comandi e il suo ambiente corrisponde al tuo.

Una configurazione di progetto tipica

Il flusso completo, dall'inizio alla fine:

# Crea la cartella del progetto
mkdir my_tool && cd my_tool

# Crea e attiva il venv
python3 -m venv .venv
source .venv/bin/activate

# Installa le dipendenze
pip install requests rich

# Salvale
pip freeze > requirements.txt

# Lavora sul tuo codice...
echo "import requests; print(requests.__version__)" > main.py
python main.py

# Quando hai finito
deactivate

Aggiungi .venv al tuo .gitignore

Non fare mai il commit della cartella .venv/. Dipende dalla piattaforma e si può ricreare da requirements.txt:

# .gitignore
.venv/
__pycache__/
*.pyc

Farne il commit gonfierebbe il repository, non funzionerebbe su altri computer e diffonderebbe i binari specifici del sistema operativo del tuo interprete.

Quale versione di Python?

Di default, python3 -m venv .venv usa il python3 che la tua shell trova per primo. Se hai più versioni di Python installate (per esempio 3.12 e 3.13), indica esplicitamente quale:

python3.13 -m venv .venv

Una volta creato il venv, il suo interprete è fissato: eseguire python dentro il venv attivo usa sempre quella versione specifica, anche se il Python di sistema cambia.

Quando qualcosa va storto

Qualche sintomo comune e la relativa soluzione:

• pip install funziona, ma gli import falliscono. Hai installato nel Python sbagliato. Attiva il venv prima di pip install e ricontrolla con which python (macOS/Linux) oppure where python (Windows).
• "ModuleNotFoundError" dopo l'attivazione. Il venv è stato creato senza certe librerie, oppure il pacchetto è stato installato in un altro venv. pip list mostra cosa c'è davvero in quello corrente.
• Script di attivazione non trovato su Windows. PowerShell potrebbe bloccare gli script non firmati. Esegui una volta Set-ExecutionPolicy -Scope CurrentUser RemoteSigned per consentire gli script locali.
• "No module named venv". Su alcune distribuzioni Linux, venv è un pacchetto separato. Su Debian/Ubuntu: sudo apt install python3-venv.

Oltre venv: Poetry, uv, pipenv

Quando ti sentirai a tuo agio con venv + pip + requirements.txt, incontrerai strumenti che racchiudono le stesse idee in modo più comodo:

• Poetry: gestisce venv, dipendenze e pacchetti con un unico pyproject.toml.
• uv: un sostituto di pip velocissimo; gestisce anche i venv.
• pipenv: uno strumento più vecchio che ha reso popolare lo schema "Pipfile + Pipfile.lock".

Sono tutti validi. Nessuno è necessario per imparare. Prendi prima confidenza con il semplice flusso di venv; il resto sono ottimizzazioni.

Cosa portarti a casa

• Ogni progetto Python reale ha il suo ambiente virtuale.
• Creane uno con python3 -m venv .venv, attivalo, poi usa pip install liberamente.
• Fissa le dipendenze con pip freeze > requirements.txt e fai il commit di quel file.
• Non fare mai il commit della cartella .venv/.
• Quando gli import fanno i capricci, controlla prima quale Python è attivo.

Prossimo argomento: lo schema __main__

Con un progetto configurato e i pacchetti installati, un ultimo idioma chiude questo capitolo: la guardia if __name__ == "__main__". Compare in quasi ogni file Python pensato per essere eseguito come script, ed è l'argomento della prossima pagina.