Ambiente virtuale Python (venv): guida pratica per creare, attivare e gestire

Nota: il video qui sotto è del 2020 e mostra comandi per Python 3.5. I comandi aggiornati a Python 3.13+ sono nel testo che segue.

Un ambiente virtuale Python è una directory isolata che contiene un interprete Python e un set indipendente di pacchetti installati. Ogni progetto può avere il proprio ambiente con versioni specifiche delle librerie, senza conflitti con altri progetti o con l’installazione di sistema. Il modulo venv, incluso nella libreria standard da Python 3.3, è lo strumento nativo per creare questi ambienti.

Senza ambienti virtuali, tutti i progetti condividono la stessa directory site-packages. Se il progetto A richiede requests==2.28 e il progetto B richiede requests==2.31, uno dei due si rompe. Il venv risolve questo problema alla radice: un ambiente per progetto, dipendenze isolate, zero conflitti.

---

Creare un ambiente virtuale con venv

Sintassi e opzioni del comando

Il comando base per creare un ambiente virtuale è:

# Crea un venv nella directory .venv (convenzione standard)
python -m venv .venv

Su sistemi dove coesistono Python 2 e Python 3, usare python3 esplicitamente:

python3 -m venv .venv

Su Windows, se Python è installato dal Microsoft Store o dall’installer ufficiale, funziona anche il launcher py:

# Usa una versione specifica di Python
py -3.13 -m venv .venv

Opzioni utili:

• --system-site-packages — rende accessibili i pacchetti installati globalmente (utile quando servono librerie di sistema come tkinter)
• --without-pip — crea il venv senza installare pip (ambiente minimale)
• --prompt nome — personalizza il prefisso mostrato nel terminale quando il venv è attivo
• --upgrade-deps — aggiorna pip e setuptools alla versione più recente durante la creazione (disponibile da Python 3.9)

Struttura della directory generata

Dopo l’esecuzione, la directory .venv contiene:

.venv/
├── bin/                    # Scripts/ su Windows
│   ├── activate            # Script di attivazione bash/zsh
│   ├── activate.csh        # Script di attivazione csh
│   ├── activate.fish       # Script di attivazione fish
│   ├── pip
│   ├── pip3
│   ├── python -> python3.13
│   └── python3 -> python3.13
├── include/                # Header C per compilare estensioni
├── lib/python3.13/
│   └── site-packages/      # Qui vengono installati i pacchetti
└── pyvenv.cfg              # Configurazione del venv

Il file pyvenv.cfg contiene il percorso dell’interprete Python di base e la configurazione dell’ambiente. Su Windows, la directory bin/ si chiama Scripts/ e i binari hanno estensione .exe.

Convenzione di naming: .venv (con il punto) è la convenzione più diffusa. Il punto iniziale rende la directory nascosta su macOS/Linux, e la maggior parte dei .gitignore template la escludono già. Evita nomi generici come env/ che possono entrare in conflitto con file .env per variabili d’ambiente.

---

Attivare e disattivare il venv

L’attivazione modifica la variabile PATH della shell corrente, anteponendo la directory bin/ (o Scripts/) del venv. Questo fa sì che i comandi python e pip puntino alle copie del venv anziché a quelle di sistema.

Attivazione su Windows

Shell	Comando
cmd.exe	.venv\Scripts\activate.bat
PowerShell	.venv\Scripts\Activate.ps1
Git Bash / MSYS2	source .venv/Scripts/activate

Attenzione: se PowerShell restituisce un errore di ExecutionPolicy, vedi la sezione Troubleshooting più avanti.

Attivazione su macOS e Linux

Shell	Comando
bash / zsh	source .venv/bin/activate
fish	source .venv/bin/activate.fish
csh / tcsh	source .venv/bin/activate.csh

Dopo l’attivazione, il prompt del terminale mostra il prefisso (.venv) per indicare che il venv è attivo. Ogni comando pip install installerà pacchetti solo dentro il venv.

Disattivazione

Per disattivare il venv e tornare all’interprete Python di sistema:

deactivate

Il comando deactivate funziona su tutti i sistemi operativi e tutte le shell.

---

Installare pacchetti nel venv con pip

pip install, requirements.txt e pip freeze

Con il venv attivo, pip installa i pacchetti esclusivamente nel site-packages del venv:

# Installa un pacchetto
pip install requests

# Installa una versione specifica
pip install requests==2.31.0

# Installa da un file requirements.txt
pip install -r requirements.txt

Per esportare l’elenco dei pacchetti installati (con le versioni esatte) in un file requirements.txt:

pip freeze > requirements.txt

Questo file permette a chiunque di ricreare lo stesso ambiente eseguendo pip install -r requirements.txt in un nuovo venv.

Aggiornare pip nel venv

Il venv viene creato con la versione di pip inclusa nell’installazione di Python, che spesso non è l’ultima disponibile. Aggiornarlo subito dopo la creazione è buona pratica:

python -m pip install --upgrade pip

In alternativa, il flag --upgrade-deps durante la creazione del venv fa la stessa cosa automaticamente:

python -m venv .venv --upgrade-deps

---

uv: l’alternativa moderna a pip e venv

Cos’è uv e perché usarlo

uv è un package manager e gestore di ambienti virtuali Python sviluppato da Astral (la stessa azienda dietro il linter Ruff). Scritto in Rust, è un singolo strumento che sostituisce pip, pip-tools, pipx e venv. La differenza principale rispetto a pip è la velocità: l’installazione dei pacchetti è 10-100x più rapida grazie al resolver parallelo e alla cache globale.

Creare e gestire ambienti virtuali con uv

Installazione:

# Su macOS/Linux
curl -LsSf https://astral.sh/uv/install.sh | sh

# Su Windows (PowerShell)
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

# Oppure con pip (qualsiasi OS)
pip install uv

Creare un venv e installare pacchetti:

# Crea un venv (molto più veloce di python -m venv)
uv venv .venv

# Installa pacchetti
uv pip install requests flask pandas

# Installa da requirements.txt
uv pip install -r requirements.txt

# Esporta le dipendenze
uv pip freeze > requirements.txt

Per progetti nuovi, uv supporta anche un workflow basato su pyproject.toml:

# Inizializza un nuovo progetto con pyproject.toml
uv init mio-progetto
cd mio-progetto

# Aggiungi una dipendenza (aggiorna pyproject.toml e crea/aggiorna il venv)
uv add requests
uv add pandas

# Sincronizza il venv con le dipendenze dichiarate
uv sync

uv vs pip: confronto prestazioni

Benchmark indicativi su un progetto con ~50 dipendenze (cache fredda):

Operazione	pip	uv	Speedup
Creazione venv	~3s	~0.1s	30x
Install da requirements.txt	~25s	~1.5s	17x
Risoluzione dipendenze	~10s	~0.5s	20x

I tempi variano in base al sistema e alla connessione, ma l’ordine di grandezza è costante. La cache globale di uv fa sì che dopo la prima installazione i pacchetti vengano copiati localmente senza download aggiuntivi.

---

Altri strumenti per ambienti virtuali Python

poetry

Poetry è un tool di dependency management che gestisce l’intero ciclo: creazione del venv, risoluzione delle dipendenze, lock file e packaging. Usa pyproject.toml come file di configurazione e genera un poetry.lock per build riproducibili.

# Inizializza un progetto
poetry init

# Aggiungi una dipendenza
poetry add requests

# Installa tutte le dipendenze (crea il venv automaticamente)
poetry install

# Attiva la shell nel venv del progetto
poetry shell

Poetry è particolarmente indicato per lo sviluppo di librerie Python che devono essere pubblicate su PyPI, grazie al supporto nativo per il build e il publishing.

pyenv + venv

pyenv non è un gestore di ambienti virtuali: è un gestore di versioni di Python. Permette di installare e switchare tra più versioni di Python sullo stesso sistema. Si usa in combinazione con venv:

# Installa Python 3.13.1
pyenv install 3.13.1

# Imposta come versione locale del progetto
pyenv local 3.13.1

# Crea il venv con quella versione
python -m venv .venv

Su Windows, pyenv non è disponibile nativamente. L’alternativa è pyenv-win, oppure il launcher py incluso nell’installer ufficiale di Python.

conda

Conda è un package manager e gestore di ambienti usato principalmente in ambito data science e scientific computing. A differenza di venv, conda gestisce anche dipendenze non-Python (librerie C, CUDA, ecc.). Se il progetto non richiede pacchetti con dipendenze native complesse, venv o uv sono scelte più leggere.

Tabella comparativa

Caratteristica	venv	uv	poetry	conda
Incluso in Python	Si	No	No	No
Velocità	Media	Molto alta	Media	Bassa
Risoluzione dipendenze	No (usa pip)	Si	Si	Si
Lock file	No	Si (uv.lock)	Si (poetry.lock)	Si
pyproject.toml	No	Si	Si	No
Dipendenze non-Python	No	No	No	Si
Caso d’uso ideale	Progetti semplici	Workflow moderno	Librerie / app	Data science

---

Best practice e configurazione progetto

.gitignore e naming convention

La directory del venv non va mai committata nel repository. Aggiungi al .gitignore:

# Virtual environment
.venv/

Usa sempre .venv (con il punto) come nome. È la convenzione riconosciuta da VS Code, PyCharm, GitHub e dalla maggior parte dei tool Python. Molti .gitignore template (come quello di GitHub per Python) la includono già.

pyproject.toml e gestione dipendenze moderna

Il file requirements.txt generato da pip freeze funziona, ma ha limiti: non distingue tra dipendenze dirette e transitive, non supporta gruppi di dipendenze (dev, test, docs), e non include metadati del progetto.

pyproject.toml (PEP 621) è il formato moderno per dichiarare le dipendenze di un progetto Python:

[project]
name = "mio-progetto"
version = "0.1.0"
requires-python = ">= 3.11"
dependencies = [
    "requests>=2.31",
    "pandas>=2.0",
]

[project.optional-dependencies]
dev = [
    "pytest>=7.0",
    "ruff>=0.4",
]

Sia uv che poetry leggono e scrivono pyproject.toml nativamente. Anche pip dalla versione 21.3 supporta l’installazione da pyproject.toml.

---

Troubleshooting

Problemi di PATH e “python: command not found”

Se il comando python non viene trovato dopo l’installazione:

• Windows: durante l’installazione di Python, selezionare la checkbox “Add Python to PATH”. Se già installato, aggiungere manualmente il percorso (es. C:\Users\utente\AppData\Local\Programs\Python\Python313) alle variabili d’ambiente. In alternativa, usare il launcher py che viene installato automaticamente.
• macOS: Python 3 non è preinstallato da Catalina in poi. Installarlo via Homebrew (brew install python) o dall’installer ufficiale python.org.
• Linux (Debian/Ubuntu): il pacchetto python3-venv potrebbe non essere installato. Risolvere con: sudo apt install python3-venv.

PowerShell ExecutionPolicy su Windows

Se l’attivazione del venv in PowerShell restituisce:

L'esecuzione di script è disabilitata nel sistema in uso.

PowerShell blocca per default l’esecuzione di script non firmati. Per risolvere, aprire PowerShell come amministratore ed eseguire:

Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser

Questa impostazione persiste tra le sessioni e consente l’esecuzione di script locali (come Activate.ps1) bloccando solo script scaricati da internet non firmati.

Permessi su macOS e Linux

Se source .venv/bin/activate restituisce “Permission denied”, lo script di attivazione non ha i permessi di esecuzione:

chmod +x .venv/bin/activate

Se pip install fallisce con errori di permessi, verificare di essere dentro il venv (controllare il prefisso (.venv) nel prompt). Se pip tenta di scrivere in directory di sistema, il venv non è attivo.

---

FAQ

È possibile spostare un venv in un’altra cartella?

No. Il file pyvenv.cfg e gli script di attivazione contengono percorsi assoluti hardcoded. Spostare la directory del venv lo rende inutilizzabile. La procedura corretta è creare un nuovo venv nella nuova posizione e reinstallare i pacchetti da requirements.txt o pyproject.toml.

Come eliminare un ambiente virtuale?

Un venv è una semplice directory. Per eliminarlo basta cancellarla:

# macOS / Linux
rm -rf .venv/

# Windows (cmd)
rmdir /s /q .venv

# Windows (PowerShell)
Remove-Item -Recurse -Force .venv

Non esiste un comando di “uninstall” — la cancellazione della directory è tutto ciò che serve.

venv, virtualenv o uv: quale usare nel 2026?

Per progetti semplici o per chi inizia: python -m venv è incluso in Python, non richiede installazioni aggiuntive e funziona ovunque.

Per workflow professionali e team: uv è la scelta migliore nel 2026. Più veloce, con risoluzione delle dipendenze integrata, lock file e supporto nativo a pyproject.toml.

Per sviluppo di librerie Python: poetry offre il workflow più completo per build, versioning e publishing su PyPI.

virtualenv resta disponibile come alternativa a venv con qualche funzionalità in più (es. ambienti più veloci da creare, supporto per plugin), ma per la maggior parte dei casi d’uso venv o uv sono sufficienti. pipenv è ancora mantenuto ma ha perso rilevanza rispetto a uv e poetry.