WSL configureren

Voordat u WSL Dashboard gebruikt, moet de WSL 2-omgeving op uw Windows-systeem correct zijn ingeschakeld en geconfigureerd. Dit document bestaat uit drie hoofdonderdelen:

1. WSL inschakelen en configureren: basisinstallatie en -configuratie van WSL 2.
2. Beschikbaar commando ≠ succesvolle installatie: legt uit dat het uitvoeren van wsl-opdrachten niet betekent dat Linux met succes kan worden geïnstalleerd.
3. Installatiefouten oplossen: controlemethoden en reparaties wanneer de installatie na configuratie nog steeds mislukt.

1. WSL inschakelen en configureren

In dit hoofdstuk wordt u door de noodzakelijke basisinstellingen geleid. Lees na afronding hoofdstuk 2 om het verschil te begrijpen tussen beschikbare opdrachten en succesvolle installatie; als de installatie nog steeds problemen geeft, raadpleeg dan hoofdstuk 3.

1.1 Systeemvereisten controleren

WSL 2 stelt minimumeisen aan de Windows-versie. Druk op Win + R en voer winver in om uw versie te controleren:

• Windows 10: versie 1903 of hoger, met buildnummer 18362 of hoger.
• Windows 11: alle versies worden ondersteund.

IMPORTANT

Als uw versie te oud is, upgrade dan eerst uw systeem via "Windows Update".

1.2 Hardwarevirtualisatie inschakelen

WSL 2 is gebaseerd op virtualisatietechnologie. U moet daarom de virtualisatietechnologie (Virtualization Technology) inschakelen in het BIOS/UEFI van het moederbord.

• Controlemethode: open "Taakbeheer" -> tabblad "Prestaties" -> "CPU".
• Status controleren: controleer of de status "Virtualisatie" rechtsonder "Ingeschakeld" aangeeft.
• Inschakelen: als dit niet is ingeschakeld, moet u de computer opnieuw opstarten, naar de BIOS/UEFI-instellingen gaan, een optie zoals Intel VT-x of AMD-V vinden en deze op Enabled zetten.

1.3 Zelfstandige Windows-functies inschakelen

U moet de functies "Windows-subsysteem voor Linux" en "Platform voor virtuele machines" van Windows inschakelen.

Methode A: via de grafische interface (aanbevolen)

1. Druk op Win + S, zoek en open "Windows-functies in- of uitschakelen".
2. Schakel de volgende twee opties in:
   • Windows-subsysteem voor Linux (Windows Subsystem for Linux)
   • Platform voor virtuele machines (Virtual Machine Platform)
3. Klik op "OK" en start de computer opnieuw op wanneer daarom wordt gevraagd.

Methode B: via de opdrachtregel (beheerdersrechten)

Voer PowerShell uit als beheerder en voer de volgende opdrachten uit:

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

# Platform voor virtuele machines inschakelen
dism.exe /online /enable-feature /featurename:VirtualMachinePlatform /all /norestart

Start na de uitvoering de computer handmatig opnieuw op.

1.4 WSL-kernel installeren/updaten

Moderne Windows-versies kunnen WSL-updates verkrijgen via de Microsoft Store.

• Downloadadres: Microsoft Store - Windows Subsystem for Linux
• Handmatige download: als u de Store niet kunt gebruiken, download dan het nieuwste .msixbundle- of .msi-pakket van WSL GitHub Releases voor offline installatie.

1.5 WSL 2 instellen als standaardversie

Om ervoor te zorgen dat nieuw geïnstalleerde distributies standaard WSL 2 gebruiken, voert u in een terminal uit:

wsl --set-default-version 2

1.6 Veelgestelde vragen

• Fout 0x80370102: meestal omdat virtualisatie niet is ingeschakeld in het BIOS, of omdat er een conflict is met Hyper-V.
• Wisselen tussen WSL 1 en WSL 2: u kunt wsl --set-version <naam-van-de-distributie> 2 gebruiken om een bestaande WSL 1-instance te upgraden naar WSL 2.

2. Beschikbaar commando ≠ succesvolle installatie

Dat opdrachten zoals wsl --version en wsl -l -v normaal kunnen worden uitgevoerd, betekent niet dat de voorwaarden voor het installeren van Linux al zijn voldaan. Het zijn verschillende fasen en kunnen niet gelijk worden gesteld.

Een beschikbaar commando betekent alleen:

• ✅ De WSL-componenten van Windows zijn ingeschakeld/geïnstalleerd
• ✅ Het opdrachtregelprogramma wsl.exe is beschikbaar
• ✅ Het systeem herkent WSL-gerelateerde opdrachten

Maar voor een succesvolle installatie van een Linux-distributie zijn extra voorwaarden nodig. Veelvoorkomende struikelblokken zijn:

1. Virtualisatie uitgeschakeld: VT-x / AMD-V is niet ingeschakeld in BIOS/UEFI; WSL 2 kan niet starten, of er wordt een virtualisatiefout gemeld bij het installeren van een distributie (controlemethode zie 1.2 Hardwarevirtualisatie inschakelen).
2. Windows-versie/buildnummer te oud: WSL 2 stelt eisen aan kernel en versie; de Home-editie of te oude bedrijfsimages kunnen onvolledige functies hebben (controlemethode zie 1.1 Systeemvereisten controleren).
3. Nog geen Linux-distributie daadwerkelijk geïnstalleerd: wsl -l -v vermeldt alleen geïnstalleerde distributies; als er niets is geïnstalleerd, is de lijst leeg. Dit betekent niet dat Ubuntu direct kan worden uitgevoerd.
4. Netwerk-/Microsoft Store-problemen: wsl --install -d <distributie> moet de image ophalen uit de Store of via het netwerk; bedrijfsnetwerken, proxy's en firewalls kunnen dit blokkeren.
5. Onvoldoende rechten: het installeren van distributies of het wijzigen van WSL-instellingen vereist beheerdersrechten.

TIP

Kort gezegd: WSL-opdrachten werken ≠ Linux is klaar – u heeft alleen het "toegangsticket", maar nog geen systeem geïnstalleerd.

3. Installatiefouten oplossen

Als wsl --install na configuratie volgens hoofdstuk 1 (of als u denkt dat u klaar bent) nog steeds mislukt, controleer dan de volgende punten in deze volgorde.

3.1 Eerst de "controle met één klik"

Voer PowerShell uit als beheerder en voer achtereenvolgens uit:

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

• ✅ Als beide opdrachten soepel worden uitgevoerd, zijn de optionele WSL-componenten ingeschakeld en zijn de virtualisatievoorwaarden in grote lijnen voldaan.
• ❌ Bij een fout wordt direct aangegeven wat er ontbreekt (bijv. Platform voor virtuele machines, Hyper-V, BIOS-virtualisatie, enz.).

Voer daarna systeminfo uit en bevestig dat in de uitvoer Virtualization Enabled In Firmware: Yes verschijnt. Als er geen fouten zijn, kunt u wsl --install zonder zorgen uitvoeren om een distributie te installeren.

NOTE

Geen enkele opdracht kan 100% garanderen dat wsl --install succesvol is, maar bovenstaande controles bevestigen of aan de installatievoorwaarden is voldaan.

3.2 Handmatige controles

Als de "controle met één klik" het probleem niet kan lokaliseren, controleer dan punt voor punt:

1. BIOS/firmwarevirtualisatie controleren: voer systeminfo uit in PowerShell als beheerder; de uitvoer moet Virtualization Enabled In Firmware: Yes bevatten.
2. Windows-functies controleren:

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

   De status van beide opdrachten moet Enabled zijn.
3. WSL-beschikbaarheid controleren: wsl --version moet normale uitvoer geven; als de melding komt dat de opdracht niet bestaat, zijn de WSL-componenten niet geïnstalleerd; ga terug naar hoofdstuk 1.
4. WSL 2-gebruik controleren (kernel & platform voor virtuele machines): wsl --set-default-version 2 moet succesvol retourneren. Veelvoorkomende oorzaken van fouten: het platform voor virtuele machines is niet ingeschakeld, of VT-x / AMD-V is niet ingeschakeld in het BIOS.

3.3 Snelle referentie voor veelvoorkomende foutoorzaken

Situatie	Beschrijving	Oplossing
Virtualisatie niet ingeschakeld in BIOS	Zeker mislukken	Opnieuw opstarten, BIOS openen en VT-x / AMD-V inschakelen (zie 1.2)
Windows 10 ouder dan 19041	wsl --install niet ondersteund	Systeem upgraden (zie 1.1)
Bedrijfsomgeving met Hyper-V/virtualisatie uitgeschakeld	Kan mislukken	Neem contact op met de systeembeheerder
Oude Home-editie	Handmatige installatie vereist	WSL-kernel handmatig installeren volgens 1.4

3.4 Fout 0xc03a0014: virtual-disk-ondersteuningsprovider niet gevonden

De foutmelding is Cannot find a virtual disk support provider for the specified file. Dit is geen probleem van de Linux-distributie zelf, maar de VHD/VHDX virtual-disk-stack van Windows werkt niet correct; WSL 2 faalt bij het registreren van een distributie of bij het maken/koppelen van ext4.vhdx.

Voer eerst een minimale verificatie uit: voer PowerShell uit als beheerder en test New-VHD (bijv. New-VHD -Path C:\test.vhdx -SizeBytes 1GB). Als deze opdracht ook dezelfde fout meldt, ligt het probleem 100% bij Windows, niet bij de distributie.

Los het probleem op in de volgende volgorde:

1. Virtual Disk-service wordt niet uitgevoerd: open services.msc, zoek de Virtual Disk-service, stel het starttype in op "Automatisch" en start deze.

2. WSL-/Virtual Machine Platform-functies niet ingeschakeld (of niet van kracht): voer de opdrachten uit 1.3 Zelfstandige Windows-functies inschakelen opnieuw uit en start daarna opnieuw op. Windows Home-editie heeft geen volledig Hyper-V, maar WSL 2 heeft alleen het platform voor virtuele machines nodig, niet de Hyper-V-beheerconsole.

3. Virtual-disk-stuurprogramma/-apparaten ontbreken: open Apparaatbeheer en controleer onder "Systeemapparaten / Opslagcontrollers" of het volgende aanwezig is:

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

   Als ze ontbreken, kunt u ze handmatig toevoegen via hdwwiz.exe (opslagcontroller → Microsoft → Microsoft VHD-loopbackcontroller) en bevestig dat de service FsDepends niet is uitgeschakeld.

4. Geïmporteerde image voldoet niet aan de WSL-eisen: bij wsl --import --vhd moet het VHDX een ext4-bestandssysteem hebben; geen LUKS-versleutelde schijf, geen normale raw.img, geen Live ISO en geen lege schijf geformatteerd in NTFS/FAT. .img / .qcow2 / .iso kunnen niet direct worden gebruikt met wsl --import --vhd.

5. Pad-/machtigings-/bestandssysteemproblemen: de doelmap moet zich op een NTFS-schijf bevinden (FAT32/exFAT werkt niet); vermijd Chinese tekens, spaties en speciale symbolen in het pad; importeer niet vanaf netwerkschijven, OneDrive of gecomprimeerde mappen; gebruik beslist een echte PowerShell als beheerder (geen gewone terminal).

6. Beschadigde systeemcomponenten: voer achtereenvolgens DISM en SFC uit om systeemcomponenten te repareren en probeer het daarna opnieuw:

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

TIP

Andere virtuele machines (VirtualBox, VMware) of sandbox-/hardening-functies van beveiligingssoftware (zoals 360, Huorong) kunnen virtual-disk-bewerkingen verstoren; u kunt ze tijdelijk uitschakelen en het opnieuw proberen tijdens het oplossen van problemen.