Setup & Config WSL

Voordat u WSL Dashboard gebruikt, moet uw Windows-systeem correct zijn ingesteld en geconfigureerd met WSL 2. Dit document bestaat uit de volgende drie delen:

1. WSL inschakelen en configureren: voer de basisinstallatie en -configuratie van WSL 2 uit.
2. Beschikbaarheid van het commando betekent geen geslaagde installatie: legt uit dat een uitvoerbaar wsl-commando niet betekent dat Linux succesvol kan worden geïnstalleerd.
3. Installatiefouten oplossen: controle- en herstelmethode wanneer de installatie na de configuratie nog steeds mislukt.

1. WSL inschakelen en configureren

In dit hoofdstuk wordt u begeleid bij de noodzakelijke basisinstellingen. Lees na dit hoofdstuk hoofdstuk 2 om het verschil te begrijpen tussen een beschikbaar commando en een geslaagde installatie; raadpleeg bij aanhoudende problemen hoofdstuk 3.

1.1 Systeemvereisten controleren

WSL 2 heeft minimale vereisten voor de Windows-versie. Druk op Win + R, voer winver in en controleer uw versie:

• Windows 10: versie 1903 of nieuwer, met een buildnummer (Build) van 18362 of hoger.
• Windows 11: alle versies worden ondersteund.

IMPORTANT

Als uw versie te oud is, moet u uw systeem eerst upgraden via "Windows Update".

1.2 Hardwarevirtualisatie inschakelen

WSL 2 draait op virtualisatietechnologie. Daarom moet virtualisatietechnologie (Virtualization Technology) zijn ingeschakeld in de BIOS/UEFI van uw moederbord.

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

1.3 Windows-gerelateerde functies inschakelen

U moet de functies "Windows-subsysteem voor Linux" en "Virtuele-machineplatform" van Windows inschakelen.

Methode A: Via de grafische interface (aanbevolen)

1. Druk op Win + S, zoek en open "Windows-onderdelen in- of uitschakelen".
2. Vink de volgende twee items aan:
   • Windows-subsysteem voor Linux (Windows Subsystem for Linux)
   • Virtuele-machineplatform (Virtual Machine Platform)
3. Klik op "OK" en start de computer opnieuw op wanneer hierom 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

# Virtuele-machineplatform inschakelen
dism.exe /online /enable-feature /featurename:VirtualMachinePlatform /all /norestart

Start de computer na uitvoering handmatig opnieuw op.

1.4 WSL-kernel installeren of bijwerken

Moderne versies van Windows kunnen WSL-updates via Microsoft Store ophalen.

• Downloadadres: Microsoft Store - Windows Subsystem for Linux
• Handmatig downloaden: als de Store niet beschikbaar is, kunt u het nieuwste .msixbundle- of .msi-installatiepakket downloaden van WSL GitHub Releases voor offline-installatie.

1.5 WSL 2 als standaardversie instellen

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

wsl --set-default-version 2

1.6 Veelgestelde vragen

• Fout 0x80370102: meestal doordat virtualisatie niet is ingeschakeld in de BIOS of door een conflict met Hyper-V.
• Wisselen tussen WSL 1 en WSL 2: u kunt wsl --set-version <分发版名称> 2 gebruiken om een bestaande WSL 1-instantie te upgraden naar WSL 2.

2. Beschikbaarheid van het commando betekent geen geslaagde installatie

Dat opdrachten als wsl --version en wsl -l -v normaal worden uitgevoerd, betekent niet dat al aan de voorwaarden voor het installeren van Linux is voldaan. Beide bevinden zich in verschillende fasen en mogen niet aan elkaar worden gelijkgesteld.

Een beschikbaar commando zegt alleen dat:

• ✅ de WSL-onderdelen in Windows al zijn ingeschakeld/geïnstalleerd
• ✅ het opdrachtregelprogramma wsl.exe beschikbaar is
• ✅ het systeem WSL-gerelateerde opdrachten herkent

Maar voor een geslaagde installatie van een Linux-distributie zijn nog aanvullende voorwaarden nodig. Veelvoorkomende knelpunten zijn:

1. Virtualisatie is uitgeschakeld: VT-x / AMD-V is niet ingeschakeld in de 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 laag: WSL 2 stelt eisen aan kernel en versie; de thuisversie en te oude bedrijfsimages kunnen mogelijk ontbrekende functies bevatten (controlemethode: zie 1.1 Systeemvereisten controleren).
3. Nog geen Linux-distributie geïnstalleerd: wsl -l -v toont alleen geïnstalleerde distributies; als er niets is geïnstalleerd, is de lijst leeg, wat niet betekent dat Ubuntu direct kan worden uitgevoerd.
4. Netwerk-/Microsoft Store-problemen: wsl --install -d <发行版> moet images ophalen uit de Store of via het netwerk; bedrijfsnetwerken, proxies en firewalls kunnen dit blokkeren.
5. Onvoldoende rechten: voor het installeren van een distributie of het wijzigen van WSL-instellingen zijn beheerdersrechten vereist.

TIP

Kort gezegd: een werkend WSL-commando is niet gelijk aan een gereed Linux-systeem; u heeft alleen het "entreebewijs" ontvangen, het systeem is nog niet echt geïnstalleerd.

3. Installatiefouten oplossen

Als wsl --install na het voltooien van de configuratie volgens hoofdstuk 1 (of wanneer u denkt dat u de configuratie hebt voltooid) nog steeds mislukt, controleer dan in de volgende volgorde.

3.1 Eerst een one-click-controle uitvoeren

Voer PowerShell uit als beheerder en voer achtereenvolgens uit:

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

• ✅ Als beide opdrachten zonder problemen worden uitgevoerd, zijn de optionele WSL-onderdelen ingeschakeld en is grotendeels aan de virtualisatievoorwaarden voldaan.
• ❌ Bij een foutmelding wordt direct aangegeven wat er ontbreekt (zoals Virtuele-machineplatform, Hyper-V, BIOS-virtualisatie, enz.).

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

NOTE

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

3.2 Handmatige controlelijst

Als de one-click-controle het probleem niet kan lokaliseren, controleer dan item voor item:

1. Controleer of BIOS-/firmwarevirtualisatie is ingeschakeld: voer systeminfo uit in een PowerShell met beheerdersrechten; in de uitvoer moet Virtualization Enabled In Firmware: Yes zichtbaar zijn.
2. Controleer of de Windows-functies zijn ingeschakeld:

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

   De status van beide opdrachten moet Enabled zijn.
3. Controleer of WSL beschikbaar is: wsl --version moet normale uitvoer geven; als wordt gemeld dat de opdracht niet bestaat, zijn de WSL-onderdelen niet geïnstalleerd; ga terug naar hoofdstuk 1.
4. Controleer of WSL 2 kan worden gebruikt (kernel en virtuele-machineplatform): wsl --set-default-version 2 moet succesvol terugkeren. Veelvoorkomende faaloorzaken: het Virtuele-machineplatform is niet ingeschakeld of VT-x / AMD-V is niet ingeschakeld in de BIOS.

3.3 Snelle naslag voor veelvoorkomende faaloorzaken

Situatie	Uitleg	Aanpak
Virtualisatie niet ingeschakeld in BIOS	Mislukt gegarandeerd	Start opnieuw op, ga naar de BIOS en schakel VT-x / AMD-V in (zie 1.2)
Windows 10 lager dan 19041	wsl --install wordt niet ondersteund	Upgrade het systeem (zie 1.1)
Hyper-V / virtualisatie uitgeschakeld in bedrijfsomgeving	Kan mislukken	Neem contact op met de systeembeheerder
Oude thuisversie van het systeem	Handmatige installatie vereist	Installeer de WSL-kernel handmatig volgens 1.4

3.4 Fout 0xc03a0014: kan geen virtuele schijfsupportprovider vinden

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 virtuele schijfstack (VHD/VHDX) van Windows werkt niet goed; WSL 2 faalt bij het registreren van een distributie en het maken/koppelen van ext4.vhdx.

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

Los het probleem op in de volgende volgorde:

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

2. De functies WSL / Virtuele-machineplatform zijn niet ingeschakeld (of niet van kracht): voer de opdrachten uit 1.3 Windows-gerelateerde functies inschakelen opnieuw uit en start daarna verplicht opnieuw op. Windows Home heeft geen volledige Hyper-V, maar WSL 2 heeft alleen het Virtuele-machineplatform nodig, niet de Hyper-V-beheerinterface.

3. Virtuele-schijfstuurprogramma's/-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, kunnen ze handmatig worden toegevoegd via hdwwiz.exe (Opslagcontrollers → Microsoft → Microsoft VHD Loopback Controller) en zorg ervoor dat de service FsDepends niet is uitgeschakeld.

4. Geïmporteerde image voldoet niet aan de WSL-vereisten: bij gebruik van wsl --import --vhd moet de VHDX een ext4-bestandssysteem hebben; geen LUKS-versleutelde schijf, gewone raw.img, Live ISO of een lege schijf die is geformatteerd als NTFS/FAT. .img / .qcow2 / .iso kunnen niet rechtstreeks worden gebruikt met wsl --import --vhd.

5. Pad-/machtigingen-/bestandssysteemproblemen: de doelmap moet op een NTFS-schijf staan (FAT32/exFAT werkt niet); vermijd Chinese tekens, spaties en speciale symbolen in het pad; importeer niet vanaf een netwerkschijf, OneDrive of gecomprimeerde mappen; gebruik altijd een echte PowerShell met beheerdersrechten (niet een gewone terminal).

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

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

TIP

Virtuele machines van derden (VirtualBox, VMware) of sandbox-/verstevigingsfuncties van beveiligingssoftware (zoals 360, Huorong) kunnen de virtuele schijfwerking verstoren; sluit deze tijdens het oplossen tijdelijk af en probeer het opnieuw.