Configurare WSL

Prima di utilizzare WSL Dashboard, il sistema Windows deve avere l'ambiente WSL 2 correttamente abilitato e configurato. Questo documento è suddiviso in tre parti principali:

1. Abilitazione e configurazione di WSL: completare l'installazione e la configurazione di base di WSL 2.
2. Un comando disponibile non equivale a un'installazione riuscita: spiega che l'eseguibilità del comando wsl non garantisce l'installazione di Linux.
3. Risoluzione dei problemi di installazione: metodi di verifica e riparazione quando l'installazione fallisce dopo la configurazione.

1. Abilitazione e configurazione di WSL

Questo capitolo guida alla configurazione di base necessaria. Al termine, leggere il Capitolo 2 per comprendere la differenza tra comando disponibile e installazione riuscita; se l'installazione presenta ancora problemi, fare riferimento al Capitolo 3.

1.1 Verifica dei requisiti di sistema

WSL 2 ha requisiti minimi per le versioni di Windows. Premere Win + R, digitare winver per verificare la propria versione:

• Windows 10: versione 1903 o successiva, con build (Build) 18362 o successiva.
• Windows 11: tutte le versioni sono supportate.

IMPORTANT

Se la versione è troppo vecchia, aggiornare prima il sistema tramite "Windows Update".

1.2 Abilitazione della virtualizzazione hardware

WSL 2 si basa sulla tecnologia di virtualizzazione, quindi è necessario abilitare la tecnologia di virtualizzazione (Virtualization Technology) nel BIOS/UEFI della scheda madre.

• Metodo di verifica: aprire "Gestione attività" -> scheda "Prestazioni" -> "CPU".
• Stato: verificare che lo stato di "Virtualizzazione" in basso a destra mostri "Abilitata".
• Come abilitarla: se non è abilitata, è necessario riavviare il computer, entrare nelle impostazioni BIOS/UEFI, trovare un'opzione simile a Intel VT-x o AMD-V e impostarla su Enabled.

1.3 Abilitazione delle funzionalità di Windows correlate

È necessario abilitare le funzionalità "Sottosistema Windows per Linux" e "Piattaforma macchina virtuale" di Windows.

Metodo A: tramite interfaccia grafica (consigliato)

1. Premere Win + S, cercare e aprire "Attiva o disattiva funzionalità di Windows".
2. Selezionare le due voci seguenti:
   • Sottosistema Windows per Linux (Windows Subsystem for Linux)
   • Piattaforma macchina virtuale (Virtual Machine Platform)
3. Fare clic su "OK" e, quando richiesto, riavviare il computer.

Metodo B: tramite riga di comando (privilegi di amministratore)

Eseguire PowerShell come amministratore e immettere i seguenti comandi:

# Abilita WSL
dism.exe /online /enable-feature /featurename:Microsoft-Windows-Subsystem-Linux /all /norestart

# Abilita la piattaforma macchina virtuale
dism.exe /online /enable-feature /featurename:VirtualMachinePlatform /all /norestart

Al termine, riavviare manualmente il computer.

1.4 Installazione/aggiornamento del kernel WSL

Le versioni moderne di Windows possono ottenere gli aggiornamenti WSL tramite Microsoft Store.

• Indirizzo di download: Microsoft Store - Windows Subsystem for Linux
• Download manuale: se lo store non è utilizzabile, è possibile scaricare l'ultimo pacchetto .msixbundle o .msi da WSL GitHub Releases per un'installazione offline.

1.5 Impostazione di WSL 2 come versione predefinita

Per garantire che le nuove distribuzioni installate utilizzino WSL 2 per impostazione predefinita, eseguire nel terminale:

wsl --set-default-version 2

1.6 Domande frequenti

• Errore 0x80370102: di solito è causato dalla virtualizzazione non abilitata nel BIOS o da conflitti con Hyper-V.
• Passaggio tra WSL 1 e WSL 2: è possibile aggiornare un'istanza WSL 1 esistente a WSL 2 con wsl --set-version <nome-distribuzione> 2.

2. Un comando disponibile non equivale a un'installazione riuscita

Il fatto che comandi come wsl --version, wsl -l -v vengano eseguiti correttamente non significa che le condizioni per installare Linux siano già soddisfatte. Si tratta di fasi diverse e non vanno equiparate.

Un comando disponibile indica soltanto che:

• ✅ I componenti WSL di Windows sono già abilitati/installati
• ✅ Lo strumento da riga di comando wsl.exe è disponibile
• ✅ Il sistema riconosce i comandi WSL correlati

Ma per installare con successo una distribuzione Linux servono condizioni aggiuntive. I punti critici più comuni sono:

1. Virtualizzazione disattivata: VT-x / AMD-V non abilitati nel BIOS/UEFI; WSL 2 non si avvia o segnala errori di virtualizzazione durante l'installazione della distribuzione (metodo di verifica: 1.2 Abilitazione della virtualizzazione hardware).
2. Versione/build di Windows troppo vecchia: WSL 2 ha requisiti su kernel e versione; le edizioni Home o le immagini enterprise datate potrebbero avere funzionalità incomplete (metodo di verifica: 1.1 Verifica dei requisiti di sistema).
3. Nessuna distribuzione Linux effettivamente installata: wsl -l -v elenca solo le distribuzioni installate; se non è stato installato nulla, l'elenco è vuoto e ciò non significa che sia possibile eseguire subito Ubuntu.
4. Problemi di rete / Microsoft Store: wsl --install -d <distribuzione> deve scaricare l'immagine dallo store o dalla rete; reti aziendali, proxy e firewall possono bloccarla.
5. Autorizzazioni insufficienti: l'installazione di distribuzioni o la modifica delle impostazioni WSL richiedono privilegi di amministratore.

TIP

In breve: i comandi WSL funzionano ≠ Linux è pronto, è come avere solo il "biglietto d'ingresso", ma il sistema non è ancora realmente installato.

3. Risoluzione dei problemi di installazione

Dopo aver completato la configurazione seguendo il Capitolo 1 (o se si ritiene di averla completata), se wsl --install fallisce ancora, controllare nell'ordine seguente.

3.1 Prima eseguire il "controllo in un clic"

Eseguire PowerShell come amministratore e immettere in sequenza:

wsl --install --no-distribution
wsl --set-default-version 2

• ✅ Se entrambi i comandi vengono eseguiti correttamente, i componenti facoltativi WSL sono abilitati e le condizioni di virtualizzazione sono sostanzialmente soddisfatte.
• ❌ In caso di errore, verrà indicato direttamente cosa manca (es. piattaforma macchina virtuale, Hyper-V, virtualizzazione BIOS, ecc.).

Eseguire quindi systeminfo e verificare nell'output che compaia Virtualization Enabled In Firmware: Yes. Se non ci sono errori, si può procedere con tranquillità all'installazione della distribuzione con wsl --install.

NOTE

Nessun comando può garantire al 100% che wsl --install riesca, ma i controlli precedenti confermano se le condizioni di installazione sono soddisfatte.

3.2 Elenco di controllo manuale

Se il "controllo in un clic" non riesce ancora a individuare il problema, verificare punto per punto:

1. Verificare se la virtualizzazione BIOS/firmware è abilitata: in PowerShell come amministratore eseguire systeminfo; nell'output deve comparire Virtualization Enabled In Firmware: Yes.
2. Verificare se le funzionalità di Windows sono abilitate:

   Get-WindowsOptionalFeature -Online -FeatureName Microsoft-Windows-Subsystem-Linux
   Get-WindowsOptionalFeature -Online -FeatureName VirtualMachinePlatform

   Lo stato di entrambi i comandi deve essere Enabled.
3. Verificare se WSL è disponibile: wsl --version deve produrre un output normale; se viene segnalato che il comando non esiste, i componenti WSL non sono installati: tornare al Capitolo 1.
4. Verificare l'uso di WSL 2 (kernel & piattaforma macchina virtuale): wsl --set-default-version 2 deve restituire esito positivo. Cause comuni di errore: piattaforma macchina virtuale non abilitata o VT-x / AMD-V non abilitati nel BIOS.

3.3 Riepilogo delle cause di errore comuni

Situazione	Spiegazione	Soluzione
Virtualizzazione non abilitata nel BIOS	Errore garantito	Riavviare, entrare nel BIOS e abilitare VT-x / AMD-V (vedere 1.2)
Windows 10 inferiore a 19041	wsl --install non supportato	Aggiornare il sistema (vedere 1.1)
Hyper-V / virtualizzazione disabilitati in ambiente enterprise	Possibile errore	Contattare l'amministratore di sistema
Sistema Home edition datato	Richiede installazione manuale	Installare manualmente il kernel WSL secondo 1.4

3.4 Errore 0xc03a0014: provider di supporto del disco virtuale non trovato

Il messaggio di errore è Cannot find a virtual disk support provider for the specified file. Il problema non riguarda la distribuzione Linux stessa, ma lo stack dei dischi virtuali VHD/VHDX di Windows che non funziona correttamente; WSL 2 fallisce nella registrazione della distribuzione e nella creazione/montaggio di ext4.vhdx.

Prima fare una verifica minima: eseguire PowerShell come amministratore e provare New-VHD (ad esempio New-VHD -Path C:\test.vhdx -SizeBytes 1GB). Se anche questo comando segnala lo stesso errore, il problema è al 100% lato Windows, non legato alla distribuzione.

Procedere con la verifica e la riparazione nell'ordine seguente:

1. Servizio Virtual Disk non in esecuzione: aprire services.msc, trovare il servizio Virtual Disk, impostare il tipo di avvio su "Automatico" e avviarlo.

2. Funzionalità WSL / piattaforma macchina virtuale non abilitate (o non attive): rieseguire i comandi di 1.3 Abilitazione delle funzionalità di Windows correlate e poi riavviare obbligatoriamente. Windows Home edition non dispone di Hyper-V completo, ma WSL 2 richiede solo la piattaforma macchina virtuale, non l'interfaccia di gestione di Hyper-V.

3. Driver/dispositivo disco virtuale mancante: aprire Gestione dispositivi e verificare la presenza, in "Dispositivi di sistema / Controller di archiviazione", di:

   • Microsoft Virtual Disk Provider
   • Microsoft Virtual Drive Enumerator
   • Microsoft VHD Loopback Controller

   Se mancano, è possibile aggiungerli manualmente tramite hdwwiz.exe (Controller di archiviazione → Microsoft → Controller di loopback Microsoft VHD) e verificare che il servizio FsDepends non sia disabilitato.

4. Immagine importata non conforme ai requisiti WSL: quando si usa wsl --import --vhd, il VHDX deve avere un file system ext4; non può essere un disco crittografato LUKS, un semplice raw.img, un Live ISO o un disco vuoto formattato NTFS/FAT. .img / .qcow2 / .iso non possono essere usati direttamente con wsl --import --vhd.

5. Problemi di percorso/autorizzazioni/file system: la directory di destinazione deve trovarsi su un disco NTFS (FAT32/exFAT non vanno bene); evitare percorsi con caratteri cinesi, spazi e simboli speciali; non importare da unità di rete, OneDrive o cartelle compresse; assicurarsi di usare un vero PowerShell da amministratore (non un normale terminale).

6. Componenti di sistema danneggiati: eseguire in sequenza DISM e SFC per riparare i componenti di sistema, quindi riprovare:

   DISM.exe /Online /Cleanup-Image /RestoreHealth
   sfc /scannow

TIP

Macchine virtuali di terze parti (VirtualBox, VMware) o funzioni di sandbox/rafforzamento di software di sicurezza (es. 360, Huorong) possono interferire con le operazioni sui dischi virtuali; durante la risoluzione si può provare a disattivarle temporaneamente.