Più progetti, più .venv: come organizzarli senza confondersi

Una .venv per progetto, il nome del progetto nel prompt e un controllo per sapere quale ambiente è attivo: come tenere in ordine più ambienti virtuali Python.

La guida agli ambienti virtuali Python (venv) in 5 minuti ti insegna a crearne uno. Dopo qualche settimana, però, i progetti diventano tre o quattro e ogni terminale mostra lo stesso (.venv): non sai più quale ambiente stai usando, né dove finisce il prossimo pip install. La soluzione non è inventare nomi diversi per le cartelle: una .venv dentro ogni progetto, il nome del progetto nel prompt e un comando che ti dice quale Python sta rispondendo.

La risposta breve: crei ogni ambiente con python -m venv .venv --prompt ., così il prompt mostra (fatture) o (report) al posto di (.venv). Prima di installare, controlli l’ambiente attivo con python -c "import sys; print(sys.prefix)". Ogni progetto tiene il suo requirements.txt, così puoi ricreare la .venv in un minuto, anche dopo averlo spostato. Nella prova su due progetti, ognuno con una versione diversa della stessa libreria, i due ambienti sono rimasti separati; dopo aver rinominato una cartella, invece, il prompt diceva ancora (fatture) mentre stava rispondendo il Python di sistema.

ℹ️ Nota / Prerequisito operativo: ti serve Python 3 installato e la guida madre letta almeno fino all’attivazione. Su Windows i comandi sono per il Prompt dei comandi; in PowerShell cambia solo lo script di attivazione (.venv\Scripts\Activate.ps1). Su macOS e Linux usa python3 per creare l’ambiente; una volta attivato, python punta al Python della .venv.

Lo schema: una cartella, una .venv

Ogni progetto ha la sua cartella e, dentro, la sua .venv. Il nome della cartella dell’ambiente resta sempre .venv: è il nome che gli editor riconoscono da soli e quello che metti una volta per tutte nel .gitignore.

Progetti/
├── fatture/
│   ├── .venv/
│   ├── requirements.txt
│   └── fatture.py
└── report/
    ├── .venv/
    ├── requirements.txt
    └── report.py

Le alternative esistono, ma costano di più quando i progetti aumentano:

Il nome del progetto nel prompt

Quando tutti gli ambienti si chiamano .venv, il prompt mostra (.venv) ovunque. L’opzione --prompt del modulo venv cambia la scritta; con il punto (--prompt .) usa il nome della cartella in cui ti trovi, come spiega la documentazione di venv.

Windows (Prompt dei comandi), dalla cartella del progetto:

python -m venv .venv --prompt .

.venv\Scripts\activate.bat

macOS / Linux:

python3 -m venv .venv --prompt .

source .venv/bin/activate

Nella prova, nella cartella fatture, dopo l’attivazione il prompt è diventato (fatture). Il nome resta scritto nel file .venv/pyvenv.cfg, che puoi aprire con un editor di testo:

home = /usr/bin
include-system-site-packages = false
version = 3.13.5
prompt = 'fatture'
executable = /usr/bin/python3.13

La riga version è utile anche più avanti: ti dice con quale Python è stato creato l’ambiente. Da Python 3.13, inoltre, venv crea dentro la .venv un piccolo file .gitignore che esclude l’intera cartella da Git. Nella prova c’era, con la riga *. Con versioni precedenti, aggiungi tu .venv/ al .gitignore del progetto.

Quale ambiente è attivo?

Il prompt è un’indicazione, non una prova. La prova è chiedere a Python dove si trova. Con l’ambiente attivo, su Windows:

python -c "import sys; print(sys.prefix)"

Su macOS e Linux il comando è lo stesso:

python -c "import sys; print(sys.prefix)"

Nella prova ho creato due progetti, fatture con tabulate 0.8.10 e report con tabulate 0.9.0. Con fatture attivo:

/workspace/vv/Progetti/fatture/.venv
Package  Version
-------- -------
pip      25.1.1
tabulate 0.8.10

La prima riga è l’output di sys.prefix, il resto di python -m pip list. Con report attivo, sys.prefix indicava report/.venv e la libreria era alla 0.9.0. Se sys.prefix mostra un percorso di sistema, come /usr su Linux o la cartella di installazione di Python su Windows, nessun ambiente è attivo e un pip install finirebbe nel Python globale.

Per passare da un progetto all’altro, nell’ordine:

1. deactivate, per uscire dall’ambiente corrente;
2. cd nella cartella dell’altro progetto;
3. attivazione della sua .venv.

Su Linux, con bash, ho provato anche ad attivare il secondo ambiente senza deactivate: lo script di attivazione ha chiuso il primo da solo e nel PATH è rimasta una sola .venv. Su Windows e macOS non l’ho verificato, quindi deactivate resta l’abitudine più sicura.

💡 Consiglio pratico — Un terminale per progetto: se lavori su due progetti nello stesso momento, apri due finestre di terminale, ognuna nella sua cartella con il suo ambiente attivo. Il prompt (fatture) o (report) ti dice a colpo d’occhio dove stai scrivendo.

Spostare o rinominare un progetto

La guida madre lo dice nell’avviso sullo spostamento: un ambiente virtuale non sopravvive allo spostamento della cartella. Nella prova ho visto come si rompe, ed è meno evidente di quanto sembri.

Ho rinominato fatture in fatture-2026 e ho riattivato la sua .venv. L’attivazione non ha dato errori e il prompt mostrava ancora (fatture), ma lo script di attivazione aveva messo nel PATH il vecchio percorso Progetti/fatture/.venv, che non esisteva più. La sessione nel terminale (bash su Debian 13):

(fatture) $ python -c "import sys; print(sys.prefix)"
bash: python: command not found
(fatture) $ python3 -c "import sys; print(sys.prefix)"
/usr
(fatture) $ .venv/bin/pip --version
bash: .venv/bin/pip: cannot execute: required file not found

python non veniva trovato e python3 rispondeva /usr, cioè il Python di sistema: con quel prompt davanti, un python3 -m pip install sarebbe finito fuori dall’ambiente. La documentazione di venv lo spiega: gli script dentro un ambiente contengono percorsi assoluti, quindi gli ambienti «non sono portabili».

La procedura che funziona: salva l’elenco dei pacchetti, sposta la cartella, cancella la .venv e ricreala.

Windows (Prompt dei comandi), prima dello spostamento, con l’ambiente attivo:

python -m pip freeze > requirements.txt

Dopo lo spostamento, nella nuova cartella:

rmdir /s /q .venv

python -m venv .venv --prompt .

.venv\Scripts\activate.bat

python -m pip install -r requirements.txt

macOS / Linux, prima dello spostamento, con l’ambiente attivo:

python -m pip freeze > requirements.txt

Dopo lo spostamento, nella nuova cartella:

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

Nella prova, dopo questi comandi, sys.prefix indicava fatture-2026/.venv, tabulate era di nuovo alla 0.8.10 e il prompt mostrava il nuovo nome, (fatture-2026). Se hai già spostato la cartella senza salvare l’elenco, su Linux ha funzionato chiamare il Python dell’ambiente per percorso: .venv/bin/python -m pip freeze > requirements.txt ha prodotto l’elenco corretto anche dopo lo spostamento.

⚠️ Attenzione — rmdir /s /q e rm -rf non chiedono conferma: lanciali solo dentro la cartella del progetto e controlla di aver scritto .venv. Un errore di battitura in quel punto cancella altro.

Fare ordine tra gli ambienti che hai già

Ogni .venv contiene un file pyvenv.cfg, quindi per trovarle tutte basta cercare quel file. Se tieni i progetti in una cartella Progetti dentro la tua cartella utente:

Windows (PowerShell):

Get-ChildItem $HOME\Progetti -Filter pyvenv.cfg -Recurse -Depth 2 -Force

macOS / Linux:

find ~/Progetti -maxdepth 3 -name pyvenv.cfg

Per vedere quanto spazio occupano, su macOS e Linux: du -sh ~/Progetti/*/.venv. Nella prova ogni ambiente, con dentro solo pip e una piccola libreria, occupava 13 MB; con librerie di calcolo o di intelligenza artificiale si sale molto. Un ambiente di un progetto che non usi più si cancella senza rischi, purché il progetto abbia il suo requirements.txt: lo ricrei quando ti serve.

Errori tipici

• Il prompt mostra il nome del progetto, ma pip install finisce nel Python di sistema → la cartella del progetto è stata spostata o rinominata dopo la creazione della .venv → controlla con sys.prefix, poi ricrea l’ambiente come nella sezione sullo spostamento.
• bash: .venv/bin/pip: cannot execute: required file not found → stesso motivo: gli script dentro .venv/bin puntano al vecchio percorso → ricrea la .venv; nel frattempo usa python -m pip invece di pip.
• Il pacchetto installato «sparisce» quando apri un nuovo terminale → l’attivazione vale solo per il terminale in cui l’hai fatta → riattiva la .venv del progetto in ogni nuova finestra.
• requirements.txt vuoto dopo pip freeze → hai lanciato il comando con l’ambiente non attivo, o con un ambiente già rotto → attiva la .venv giusta, verifica con sys.prefix e rilancia.
• Su Windows rmdir risponde che il file è in uso → un terminale o l’editor sta ancora usando il Python della .venv → lancia deactivate, chiudi l’editor del progetto e riprova.

Domande Frequenti (FAQ)

Posso usare la stessa .venv per due progetti che usano le stesse librerie?

Funziona finché le versioni coincidono. Il giorno in cui uno dei due progetti aggiorna una libreria, rompe l’altro senza avvisare. Due ambienti costano qualche decina di megabyte; il tempo per capire quale progetto si è rotto costa di più.

Perché chiamare tutte le cartelle .venv e non venv-fatture, venv-report?

Perché il nome della cartella dell’ambiente non serve a distinguerle: le distingue la cartella del progetto in cui si trovano. Con lo stesso nome ovunque, il .gitignore, gli editor e i comandi di attivazione sono identici in tutti i progetti. Per riconoscerle nel terminale c’è --prompt ..

Posso cambiare il nome nel prompt di una .venv già creata?

Il nome è scritto nella riga prompt di pyvenv.cfg e negli script di attivazione. La strada più semplice è ricreare l’ambiente: salvi requirements.txt, cancelli la .venv e la ricrei con --prompt . come nella sezione sullo spostamento.

Come faccio a sapere con quale versione di Python è stata creata una .venv?

Apri .venv/pyvenv.cfg: la riga version lo indica. Se hai aggiornato Python e un progetto vecchio smette di funzionare, ricrea la sua .venv con il Python nuovo e reinstalla da requirements.txt.

VS Code o Cursor riconoscono la .venv del progetto?

L’estensione Python di VS Code cerca gli ambienti nella cartella aperta, e una .venv nella radice del progetto viene di solito proposta in automatico. Se l’editor usa un altro Python, scegli quello della .venv con il comando Python: Select Interpreter dalla tavolozza dei comandi.

Serve un requirements.txt anche per progetti piccoli?

Sì, appena installi la prima libreria. È il file che ti permette di cancellare la .venv senza paura e di ricrearla dopo uno spostamento, un aggiornamento di Python o su un altro computer.

L’abitudine che tiene in ordine i progetti

Ogni nuovo progetto parte con gli stessi tre passi: cartella, .venv con --prompt ., requirements.txt aggiornato a ogni installazione. Prima di un pip install guardi il prompt; se hai un dubbio, sys.prefix. Per scegliere cosa installare davvero, la guida quando usare pip install e quando no ti aiuta a evitare librerie superflue; per sistemare il resto della cartella c’è la struttura minima di un progetto Python. Se ti serve un piccolo script già pronto per un progetto tuo, con il suo ambiente e il suo requirements.txt, è il tipo di lavoro che realizzo su richiesta. Per ripassare creazione e attivazione, torna agli ambienti virtuali Python (venv) in 5 minuti.