Setup & Config WSL

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

1. Setup e configurazione di WSL: completare l'installazione e la configurazione di base di WSL 2.
2. Un comando disponibile non significa installazione riuscita: spiega che un comando wsl eseguibile non significa che Linux possa essere installato con successo.
3. Risoluzione dei problemi di installazione: metodi di verifica e riparazione quando l'installazione fallisce ancora dopo la configurazione.

1. Setup e configurazione di WSL

Questo capitolo vi guiderà nel completamento delle impostazioni di base necessarie. Dopo aver completato questo capitolo, leggete il capitolo 2 per comprendere la differenza tra disponibilità del comando e successo dell'installazione; se l'installazione presenta ancora problemi, fate riferimento al capitolo 3.

1.1 Verificare i requisiti di sistema

WSL 2 ha requisiti minimi di versione di Windows. Premete Win + R, digitate winver per verificare la vostra versione:

• Windows 10: versione 1903 o successiva, e il numero di build deve essere 18362 o superiore.
• Windows 11: tutte le versioni sono supportate.

IMPORTANT

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

1.2 Abilitare la virtualizzazione hardware

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

• Metodo di verifica: aprite il "Task Manager" -> scheda "Prestazioni" -> "CPU".
• Controllare lo stato: confermate che lo stato "Virtualizzazione" in basso a destra mostri "Abilitato".
• Modalità di abilitazione: se non è abilitata, è necessario riavviare il computer, accedere alle impostazioni BIOS/UEFI, trovare un'opzione simile a Intel VT-x o AMD-V e impostarla su Enabled.

1.3 Abilitare le funzionalità correlate di Windows

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

Metodo A: tramite l'interfaccia grafica (consigliato)

1. Premete Win + S, cercate e aprite "Attiva o disattiva funzionalità di Windows".
2. Spuntate i due elementi seguenti:
   • Sottosistema Windows per Linux (Windows Subsystem for Linux)
   • Piattaforma macchina virtuale (Virtual Machine Platform)
3. Fate clic su "OK" e riavviate il computer quando richiesto.

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

Eseguite PowerShell come amministratore ed eseguite i seguenti comandi:

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

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

Dopo l'esecuzione, riavviate manualmente il computer.

1.4 Installare o aggiornare il kernel di WSL

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

• URL di download: Microsoft Store - Windows Subsystem for Linux
• Download manuale: se non è possibile usare lo Store, potete scaricare il pacchetto di installazione .msixbundle o .msi più recente da WSL GitHub Releases per un'installazione offline.

1.5 Impostare WSL 2 come versione predefinita

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

wsl --set-default-version 2

1.6 Problemi comuni

• Errore 0x80370102: di solito è dovuto alla virtualizzazione non abilitata nel BIOS o a un conflitto con Hyper-V.
• Passaggio tra WSL 1 e WSL 2: potete usare wsl --set-version <nome della distribuzione> 2 per aggiornare un'istanza WSL 1 esistente a WSL 2.

2. Un comando disponibile non significa installazione riuscita

Comandi come wsl --version, wsl -l -v possono essere eseguiti correttamente, ma questo non significa che le condizioni per installare Linux siano già soddisfatte. Le due cose si trovano in fasi diverse e non vanno equiparate.

Un comando disponibile indica solo che:

• ✅ il componente WSL è abilitato/installato in Windows
• ✅ lo strumento da riga di comando wsl.exe è disponibile
• ✅ il sistema riconosce i comandi relativi a WSL

Ma per installare con successo una distribuzione Linux sono necessarie condizioni aggiuntive. I punti di blocco comuni sono:

1. La virtualizzazione è disattivata: VT-x / AMD-V non è abilitato nel BIOS/UEFI, WSL 2 non può avviarsi o viene segnalato un errore di virtualizzazione durante l'installazione della distribuzione (metodo di verifica: vedere 1.2 Abilitare la virtualizzazione hardware).
2. Versione/build di Windows troppo vecchia: WSL 2 ha requisiti di kernel e versione; l'edizione Home o le immagini aziendali troppo vecchie possono avere funzionalità incomplete (metodo di verifica: vedere 1.1 Verificare i requisiti di sistema).
3. Nessuna distribuzione Linux effettivamente installata: wsl -l -v elenca solo le distribuzioni installate; se non è installato nulla, l'elenco è vuoto, il che non significa che possiate eseguire Ubuntu direttamente.
4. Problemi di rete / Microsoft Store: wsl --install -d <distribuzione> deve scaricare l'immagine dallo Store o dalla rete; la rete aziendale, i proxy e i firewall possono bloccarlo.
5. Permessi insufficienti: installare una distribuzione o modificare le impostazioni di WSL richiede privilegi di amministratore.

TIP

In breve: un comando WSL disponibile non significa Linux pronto; avete solo ottenuto un "biglietto d'ingresso", ma non avete ancora installato davvero il sistema.

3. Risoluzione dei problemi di installazione

Dopo aver completato la configurazione secondo il capitolo 1 (o se pensate di averla completata), se wsl --install fallisce ancora, controllate nel seguente ordine.

3.1 Eseguire prima il controllo in un solo comando

Eseguite in sequenza, con privilegi di amministratore, in PowerShell:

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

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

Eseguite poi systeminfo e confermate che nell'output compaia Virtualization Enabled In Firmware: Yes. Se nessuno dei controlli precedenti segnala errori, in genere potete eseguire wsl --install con tranquillità per installare una distribuzione.

NOTE

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

3.2 Elenco di controllo manuale

Se il controllo in un solo comando non riesce ancora a individuare il problema, verificate punto per punto:

1. Verificare se la virtualizzazione BIOS/firmware è abilitata: in PowerShell come amministratore, eseguite systeminfo; l'output deve mostrare 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 indicato che il comando non esiste, il componente WSL non è installato; tornate al capitolo 1.
4. Verificare se WSL 2 è disponibile (kernel e piattaforma macchina virtuale): wsl --set-default-version 2 deve restituire successo. Cause comuni di errore: la piattaforma macchina virtuale non è abilitata oppure VT-x / AMD-V non è abilitato nel BIOS.

3.3 Riferimento rapido delle cause di errore comuni

Situazione	Spiegazione	Modalità di intervento
Virtualizzazione non abilitata nel BIOS	Fallisce di sicuro	Riavviare e abilitare VT-x / AMD-V nel BIOS (vedere 1.2)
Windows 10 inferiore a 19041	wsl --install non supportato	Aggiornare il sistema (vedere 1.1)
Hyper-V / virtualizzazione disabilitata nell'ambiente aziendale	Può fallire	Contattare l'amministratore di sistema
Vecchia edizione Home	Richiede installazione manuale	Installare manualmente il kernel di WSL secondo 1.4

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

Il messaggio di errore è Cannot find a virtual disk support provider for the specified file. Non è un problema della distribuzione Linux in sé, ma dello stack di dischi virtuali VHD/VHDX di Windows che non funziona correttamente: WSL 2 fallisce durante la registrazione della distribuzione e la creazione/montaggio di ext4.vhdx.

Fate prima una verifica minima: eseguite PowerShell come amministratore e provate 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 e non riguarda la distribuzione.

Verificate e riparate nel seguente ordine:

1. Il servizio Virtual Disk non è in esecuzione: aprite services.msc, cercate il servizio Virtual Disk, impostate il tipo di avvio su "Automatico" e avviatelo.

2. Funzionalità WSL / piattaforma macchina virtuale non abilitate (o non efficaci): rieseguite i comandi di 1.3 Abilitare le funzionalità correlate di Windows e poi dovete riavviare. L'edizione Home di Windows non ha Hyper-V completo, ma WSL 2 ha bisogno solo della piattaforma macchina virtuale, non dell'interfaccia di gestione di Hyper-V.

3. Driver/dispositivi di disco virtuale mancanti: aprite Gestione dispositivi e verificate se in "Dispositivi di sistema / Controller di archiviazione" sono presenti i seguenti elementi:

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

   Se mancano, potete aggiungerli manualmente con hdwwiz.exe (Controller di archiviazione → Microsoft → Microsoft VHD Loopback Controller) e confermate che il servizio FsDepends non sia disabilitato.

4. L'immagine importata non soddisfa i requisiti di WSL: quando si usa wsl --import --vhd, il VHDX deve essere un file system ext4; non può essere un disco crittografato LUKS, una raw.img normale, una ISO live o un disco vuoto formattato in NTFS/FAT. I file .img / .qcow2 / .iso non possono essere usati direttamente con wsl --import --vhd.

5. Problemi di percorso/permessi/file system: la directory di destinazione deve trovarsi su un disco NTFS (FAT32/exFAT non vanno bene); evitate caratteri cinesi, spazi e simboli speciali nel percorso; non importate da unità di rete, OneDrive o cartelle compresse; usate sempre una vera PowerShell di amministratore (non un terminale normale).

6. Componenti di sistema danneggiati: eseguite in sequenza DISM e SFC per riparare i componenti di sistema, poi riprovate:

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

TIP

Le macchine virtuali di terze parti (VirtualBox, VMware) o le funzioni sandbox/rafforzamento dei software di sicurezza (come 360, Huorong) possono interferire con le operazioni sui dischi virtuali; potete disattivarle temporaneamente durante la risoluzione dei problemi.