WSL konfigurieren

Bevor Sie WSL Dashboard verwenden, muss auf Ihrem Windows-System die WSL 2-Umgebung korrekt aktiviert und konfiguriert sein. Dieses Dokument ist in drei Hauptteile gegliedert:

1. Aktivieren und Konfigurieren von WSL: Grundinstallation und -konfiguration von WSL 2.
2. Verfügbarer Befehl ≠ erfolgreiche Installation: Erklärt, dass ein ausführbarer wsl-Befehl nicht bedeutet, dass Linux erfolgreich installiert werden kann.
3. Fehlerbehebung bei Installationsfehlern: Prüf- und Reparaturmethoden, wenn die Installation nach der Konfiguration weiterhin fehlschlägt.

1. WSL aktivieren und konfigurieren

Dieses Kapitel führt Sie durch die notwendigen Grundeinstellungen. Lesen Sie nach Abschluss Kapitel 2, um den Unterschied zwischen verfügbarem Befehl und erfolgreicher Installation zu verstehen; falls die Installation weiterhin Probleme bereitet, lesen Sie Kapitel 3.

1.1 Systemanforderungen prüfen

WSL 2 stellt Mindestanforderungen an die Windows-Version. Drücken Sie Win + R und geben Sie winver ein, um Ihre Version zu prüfen:

• Windows 10: Version 1903 oder höher, mit Build-Nummer 18362 oder höher.
• Windows 11: Alle Versionen werden unterstützt.

IMPORTANT

Wenn Ihre Version zu alt ist, aktualisieren Sie Ihr System zuerst über „Windows Update".

1.2 Hardware-Virtualisierung aktivieren

WSL 2 basiert auf Virtualisierungstechnologie; Sie müssen daher die Virtualisierungstechnologie (Virtualization Technology) im BIOS/UEFI des Mainboards aktivieren.

• Prüfmethode: Öffnen Sie den „Task-Manager" -> Registerkarte „Leistung" -> „CPU".
• Status prüfen: Stellen Sie sicher, dass der Status „Virtualisierung" unten rechts „Aktiviert" anzeigt.
• So aktivieren Sie sie: Falls sie nicht aktiviert ist, starten Sie den Computer neu, gehen Sie in die BIOS/UEFI-Einstellungen, suchen Sie eine Option wie Intel VT-x oder AMD-V und setzen Sie sie auf Enabled.

1.3 Zugehörige Windows-Funktionen aktivieren

Sie müssen die Funktionen „Windows-Subsystem für Linux" und „Plattform für virtuelle Maschinen" von Windows aktivieren.

Methode A: Über die grafische Oberfläche (empfohlen)

1. Drücken Sie Win + S, suchen Sie und öffnen Sie „Windows-Funktionen aktivieren oder deaktivieren".
2. Aktivieren Sie die folgenden beiden Optionen:
   • Windows-Subsystem für Linux (Windows Subsystem for Linux)
   • Plattform für virtuelle Maschinen (Virtual Machine Platform)
3. Klicken Sie auf „OK" und starten Sie den Computer neu, wenn Sie dazu aufgefordert werden.

Methode B: Über die Befehlszeile (Administratorrechte)

Führen Sie PowerShell als Administrator aus und führen Sie die folgenden Befehle aus:

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

# Plattform für virtuelle Maschinen aktivieren
dism.exe /online /enable-feature /featurename:VirtualMachinePlatform /all /norestart

Starten Sie nach der Ausführung den Computer manuell neu.

1.4 WSL-Kernel installieren/aktualisieren

Moderne Windows-Versionen können WSL-Updates über den Microsoft Store beziehen.

• Download-Adresse: Microsoft Store - Windows Subsystem for Linux
• Manueller Download: Wenn Sie den Store nicht nutzen können, laden Sie das neueste .msixbundle- oder .msi-Paket von WSL GitHub Releases für eine Offline-Installation herunter.

1.5 WSL 2 als Standardversion festlegen

Um sicherzustellen, dass neu installierte Distributionen standardmäßig WSL 2 verwenden, führen Sie im Terminal aus:

wsl --set-default-version 2

1.6 Häufige Fragen

• Fehler 0x80370102: In der Regel, weil die Virtualisierung im BIOS nicht aktiviert ist oder ein Konflikt mit Hyper-V besteht.
• Wechsel zwischen WSL 1 und WSL 2: Sie können wsl --set-version <Name-der-Distribution> 2 verwenden, um eine vorhandene WSL-1-Instanz auf WSL 2 zu aktualisieren.

2. Verfügbarer Befehl ≠ erfolgreiche Installation

Dass Befehle wie wsl --version oder wsl -l -v problemlos ausgeführt werden können, bedeutet nicht, dass die Voraussetzungen für die Linux-Installation erfüllt sind. Es handelt sich um verschiedene Phasen, die nicht gleichgesetzt werden dürfen.

Ein verfügbarer Befehl bedeutet nur:

• ✅ Die WSL-Komponenten von Windows sind aktiviert/installiert
• ✅ Das Befehlszeilentool wsl.exe ist verfügbar
• ✅ Das System erkennt WSL-bezogene Befehle

Aber für eine erfolgreiche Installation einer Linux-Distribution sind zusätzliche Bedingungen erforderlich. Häufige Stolperfallen sind:

1. Virtualisierung deaktiviert: VT-x / AMD-V ist im BIOS/UEFI nicht aktiviert, WSL 2 kann nicht starten, oder bei der Installation der Distribution wird ein Virtualisierungsfehler gemeldet (Prüfmethode siehe 1.2 Hardware-Virtualisierung aktivieren).
2. Windows-Version/Build zu alt: WSL 2 stellt Anforderungen an Kernel und Version; die Home-Edition oder zu alte Firmen-Images können unvollständige Funktionen haben (Prüfmethode siehe 1.1 Systemanforderungen prüfen).
3. Noch keine Linux-Distribution tatsächlich installiert: wsl -l -v listet nur installierte Distributionen auf; wenn nichts installiert ist, ist die Liste leer, was nicht bedeutet, dass man Ubuntu direkt ausführen kann.
4. Netzwerk-/Microsoft-Store-Probleme: wsl --install -d <Distribution> muss das Image aus dem Store oder Netzwerk laden; Firmennetzwerke, Proxys und Firewalls können blockieren.
5. Unzureichende Berechtigungen: Das Installieren von Distributionen oder das Ändern von WSL-Einstellungen erfordert Administratorrechte.

TIP

Kurz gesagt: WSL-Befehle funktionieren ≠ Linux ist bereit – Sie haben nur die „Eintrittskarte", aber noch kein System installiert.

3. Fehlerbehebung bei Installationsfehlern

Wenn wsl --install nach der Konfiguration gemäß Kapitel 1 (oder wenn Sie glauben, sie abgeschlossen zu haben) weiterhin fehlschlägt, prüfen Sie die folgenden Punkte in dieser Reihenfolge.

3.1 Zuerst die „Ein-Klick-Prüfung"

Führen Sie PowerShell als Administrator aus und führen Sie nacheinander aus:

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

• ✅ Wenn beide Befehle problemlos ausgeführt werden, sind die optionalen WSL-Komponenten aktiviert und die Virtualisierungsbedingungen im Wesentlichen erfüllt.
• ❌ Bei einem Fehler wird direkt angezeigt, was fehlt (z. B. Plattform für virtuelle Maschinen, Hyper-V, BIOS-Virtualisierung usw.).

Führen Sie anschließend systeminfo aus und bestätigen Sie, dass in der Ausgabe Virtualization Enabled In Firmware: Yes erscheint. Wenn keine Fehler auftreten, können Sie wsl --install bedenkenlos ausführen, um die Distribution zu installieren.

NOTE

Kein Befehl kann zu 100 % garantieren, dass wsl --install erfolgreich ist, aber die obigen Prüfungen bestätigen, ob die Installationsbedingungen erfüllt sind.

3.2 Manuelle Prüfliste

Wenn die „Ein-Klick-Prüfung" das Problem weiterhin nicht lokalisieren kann, prüfen Sie Punkt für Punkt:

1. BIOS/Firmware-Virtualisierung prüfen: Führen Sie in Administrator-PowerShell systeminfo aus; die Ausgabe muss Virtualization Enabled In Firmware: Yes enthalten.
2. Windows-Funktionen prüfen:

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

   Der Status beider Befehle muss Enabled sein.
3. WSL-Verfügbarkeit prüfen: wsl --version sollte eine normale Ausgabe liefern; wenn die Meldung kommt, dass der Befehl nicht existiert, sind die WSL-Komponenten nicht installiert; kehren Sie zu Kapitel 1 zurück.
4. WSL 2-Nutzung prüfen (Kernel & Plattform für virtuelle Maschinen): wsl --set-default-version 2 sollte erfolgreich zurückkehren. Häufige Fehlerursachen: Die Plattform für virtuelle Maschinen ist nicht aktiviert oder VT-x / AMD-V ist im BIOS nicht aktiviert.

3.3 Schnellreferenz zu häufigen Fehlerursachen

Situation	Beschreibung	Lösung
Virtualisierung im BIOS nicht aktiviert	Sicherer Fehlschlag	Neustart, BIOS öffnen und VT-x / AMD-V aktivieren (siehe 1.2)
Windows 10 älter als 19041	wsl --install nicht unterstützt	System aktualisieren (siehe 1.1)
Unternehmensumgebung mit deaktiviertem Hyper-V / Virtualisierung	Kann fehlschlagen	Systemadministrator kontaktieren
Alte Home-Edition	Manuelle Installation erforderlich	WSL-Kernel gemäß 1.4 manuell installieren

3.4 Fehler 0xc03a0014: Virtual-Disk-Support-Anbieter nicht gefunden

Die Fehlermeldung lautet Cannot find a virtual disk support provider for the specified file. Dies ist kein Problem der Linux-Distribution selbst, sondern der VHD/VHDX-Virtual-Disk-Stack von Windows funktioniert nicht ordnungsgemäß; WSL 2 schlägt beim Registrieren der Distribution oder beim Erstellen/Einhängen von ext4.vhdx fehl.

Führen Sie zuerst eine minimale Verifikation durch: Führen Sie PowerShell als Administrator aus und testen Sie New-VHD (z. B. New-VHD -Path C:\test.vhdx -SizeBytes 1GB). Wenn dieser Befehl ebenfalls denselben Fehler meldet, liegt das Problem zu 100 % bei Windows, nicht bei der Distribution.

Führen Sie die Fehlersuche und Reparatur in dieser Reihenfolge durch:

1. Virtual Disk-Dienst wird nicht ausgeführt: Öffnen Sie services.msc, suchen Sie den Dienst Virtual Disk, setzen Sie den Starttyp auf „Automatisch" und starten Sie ihn.

2. WSL-/Virtual Machine Platform-Funktionen nicht aktiviert (oder nicht wirksam): Führen Sie die Befehle aus 1.3 Zugehörige Windows-Funktionen aktivieren erneut aus und starten Sie anschließend neu. Die Windows-Home-Edition hat kein vollständiges Hyper-V, aber WSL 2 benötigt nur die Plattform für virtuelle Maschinen, nicht die Hyper-V-Verwaltungskonsole.

3. Virtual-Disk-Treiber/-Geräte fehlen: Öffnen Sie den Geräte-Manager und prüfen Sie unter „Systemgeräte / Speichercontroller", ob Folgendes vorhanden ist:

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

   Falls sie fehlen, können Sie sie manuell über hdwwiz.exe hinzufügen (Speichercontroller → Microsoft → Microsoft VHD Loopback Controller) und bestätigen, dass der Dienst FsDepends nicht deaktiviert ist.

4. Importiertes Image entspricht nicht den WSL-Anforderungen: Bei wsl --import --vhd muss das VHDX ein ext4-Dateisystem sein; kein LUKS-verschlüsseltes Laufwerk, keine normale raw.img, kein Live-ISO und keine in NTFS/FAT formatierte leere Platte. .img / .qcow2 / .iso können nicht direkt mit wsl --import --vhd verwendet werden.

5. Pfad-/Berechtigungs-/Dateisystemprobleme: Das Zielverzeichnis muss auf einem NTFS-Laufwerk liegen (FAT32/exFAT geht nicht); vermeiden Sie chinesische Zeichen, Leerzeichen und Sonderzeichen im Pfad; importieren Sie nicht von Netzlaufwerken, OneDrive oder komprimierten Ordnern; verwenden Sie unbedingt eine echte Administrator-PowerShell (kein normales Terminal).

6. Beschädigte Systemkomponenten: Führen Sie nacheinander DISM und SFC zur Reparatur der Systemkomponenten aus und versuchen Sie es dann erneut:

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

TIP

Fremde VMs (VirtualBox, VMware) oder Sandbox-/Härtungsfunktionen von Sicherheitssoftware (z. B. 360, Huorong) können Virtual-Disk-Operationen stören; bei der Fehlersuche können Sie sie vorübergehend deaktivieren und erneut versuchen.