Konfiguracja WSL

Przed skorzystaniem z WSL Dashboard system Windows musi poprawnie włączyć i skonfigurować środowisko WSL 2. Niniejsza dokumentacja składa się z trzech głównych części:

1. Włączanie i konfiguracja WSL: podstawowe kroki instalacji i konfiguracji WSL 2.
2. Dostępność poleceń nie oznacza udanej instalacji: wyjaśnia, że działające polecenie wsl nie gwarantuje pomyślnej instalacji systemu Linux.
3. Rozwiązywanie problemów z instalacją: sposoby sprawdzania i naprawy, gdy instalacja nadal kończy się błędem po wykonaniu konfiguracji.

1. Włączanie i konfiguracja WSL

Ten rozdział poprowadzi Cię przez niezbędne ustawienia podstawowe. Po ukończeniu tego rozdziału przeczytaj rozdział 2, aby poznać różnicę między dostępnością poleceń a udaną instalacją; jeśli instalacja nadal sprawia problemy, zajrzyj do rozdziału 3.

1.1 Sprawdzanie wymagań systemowych

WSL 2 ma minimalne wymagania dotyczące wersji systemu Windows. Naciśnij Win + R, wpisz winver i sprawdź swoją wersję:

• Windows 10: wersja 1903 lub nowsza, a numer kompilacji (Build) musi wynosić 18362 lub więcej.
• Windows 11: wszystkie wersje są obsługiwane.

IMPORTANT

Jeśli Twoja wersja jest zbyt stara, najpierw zaktualizuj system przez Windows Update.

1.2 Włączanie wirtualizacji sprzętowej

WSL 2 działa w oparciu o technologię wirtualizacji, dlatego w BIOS/UEFI płyty głównej należy włączyć technologię wirtualizacji (Virtualization Technology).

• Sposób sprawdzenia: otwórz "Menedżer zadań" -> zakładkę "Wydajność" -> "CPU".
• Sprawdzenie stanu: upewnij się, że status "Wirtualizacja" w prawym dolnym rogu pokazuje "Włączona".
• Sposób włączenia: jeśli nie jest włączona, zrestartuj komputer, wejdź do ustawień BIOS/UEFI, znajdź opcję podobną do Intel VT-x lub AMD-V i ustaw ją na Enabled.

1.3 Włączanie powiązanych funkcji Windows

Musisz włączyć funkcje "Podsystem Windows dla systemu Linux" i "Platforma maszyn wirtualnych".

Metoda A: Przez interfejs graficzny (zalecane)

1. Naciśnij Win + S, wyszukaj i otwórz "Włącz lub wyłącz funkcje systemu Windows".
2. Zaznacz następujące dwie pozycje:
   • Podsystem Windows dla systemu Linux (Windows Subsystem for Linux)
   • Platforma maszyn wirtualnych (Virtual Machine Platform)
3. Kliknij "OK" i zrestartuj komputer, gdy pojawi się odpowiedni monit.

Metoda B: Przez wiersz poleceń (uprawnienia administratora)

Uruchom program PowerShell jako administrator i wykonaj następujące polecenia:

# Włącz WSL
dism.exe /online /enable-feature /featurename:Microsoft-Windows-Subsystem-Linux /all /norestart

# Włącz platformę maszyn wirtualnych
dism.exe /online /enable-feature /featurename:VirtualMachinePlatform /all /norestart

Po wykonaniu ręcznie zrestartuj komputer.

1.4 Instalacja lub aktualizacja jądra WSL

Nowoczesne wersje systemu Windows mogą pobierać aktualizacje WSL przez Microsoft Store.

• Adres pobierania: Microsoft Store — Windows Subsystem for Linux
• Pobieranie ręczne: jeśli sklep jest niedostępny, możesz pobrać najnowszy pakiet instalacyjny .msixbundle lub .msi ze strony WSL GitHub Releases w celu instalacji offline.

1.5 Ustawienie WSL 2 jako wersji domyślnej

Aby nowo instalowane dystrybucje domyślnie używały WSL 2, wykonaj w terminalu:

wsl --set-default-version 2

1.6 Częste problemy

• Błąd 0x80370102: zwykle wynika z niewłączonej wirtualizacji w BIOS lub z konfliktu z Hyper-V.
• Przełączanie między WSL 1 a WSL 2: możesz użyć polecenia wsl --set-version <nazwa dystrybucji> 2, aby uaktualnić istniejącą instancję WSL 1 do WSL 2.

2. Dostępność poleceń nie oznacza udanej instalacji

To, że polecenia wsl --version, wsl -l -v i podobne wykonują się bez błędów, nie oznacza, że warunki do instalacji systemu Linux są już spełnione. To różne etapy, których nie można ze sobą utożsamiać.

Dostępność poleceń świadczy tylko o tym, że:

• ✅ składniki WSL w systemie Windows zostały już włączone/zainstalowane
• ✅ narzędzie wiersza poleceń wsl.exe jest dostępne
• ✅ system rozpoznaje polecenia związane z WSL

Ale do pomyślnej instalacji dystrybucji systemu Linux potrzebne są dodatkowe warunki. Najczęściej utykasz na następujących rzeczach:

1. Wirtualizacja jest wyłączona: w BIOS/UEFI nie włączono VT-x / AMD-V, przez co WSL 2 nie uruchamia się lub podczas instalacji dystrybucji zgłaszany jest błąd wirtualizacji (sposób sprawdzenia — 1.2 Włączanie wirtualizacji sprzętowej).
2. Zbyt stara wersja/kompilacja systemu Windows: WSL 2 ma wymagania co do jądra i wersji; w wersji Home lub zbyt starych obrazach korporacyjnych funkcje mogą być niekompletne (sposób sprawdzenia — 1.1 Sprawdzanie wymagań systemowych).
3. Dystrybucja systemu Linux nie została jeszcze zainstalowana: polecenie wsl -l -v wyświetla tylko zainstalowane dystrybucje; jeśli nic nie zainstalowano, lista będzie pusta, co nie oznacza, że można od razu uruchomić Ubuntu.
4. Problemy z siecią / Microsoft Store: polecenie wsl --install -d <dystrybucja> musi pobierać obraz ze sklepu lub z sieci; sieć firmowa, proxy i zapora sieciowa mogą to blokować.
5. Niewystarczające uprawnienia: do instalacji dystrybucji lub zmiany ustawień WSL wymagane są uprawnienia administratora.

TIP

Mówiąc wprost: działające polecenia WSL ≠ Linux gotowy — masz tylko "bilet wstępu", ale sam system nie został jeszcze zainstalowany.

3. Rozwiązywanie problemów z instalacją

Jeśli po konfiguracji zgodnie z rozdziałem 1 (lub gdy uważasz, że konfiguracja została wykonana) polecenie wsl --install nadal kończy się błędem, sprawdzaj w podanej kolejności.

3.1 Najpierw wykonaj "szybkie sprawdzenie"

Uruchom program PowerShell jako administrator i wykonaj kolejno:

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

• ✅ Jeśli oba polecenia wykonają się bez błędów, opcjonalne składniki WSL są włączone, a warunki wirtualizacji w zasadzie spełnione.
• ❌ Jeśli wystąpi błąd, system od razu podpowie, czego brakuje (np. platforma maszyn wirtualnych, Hyper-V, wirtualizacja BIOS itd.).

Następnie wykonaj systeminfo i potwierdź, że w wyniku pojawia się Virtualization Enabled In Firmware: Yes. Jeśli powyżej nie ma żadnych błędów, możesz spokojnie wykonać wsl --install, aby zainstalować dystrybucję.

NOTE

Żadne polecenie nie może w 100% zagwarantować powodzenia wsl --install, ale powyższe sprawdzenia potwierdzają, czy warunki instalacji są spełnione.

3.2 Ręczna lista kontrolna

Jeśli "szybkie sprawdzenie" nie pomogło zlokalizować problemu, sprawdzaj punkt po punkcie:

1. Sprawdź, czy włączona jest wirtualizacja BIOS/oprogramowania układowego: w programie PowerShell uruchomionym jako administrator wykonaj systeminfo; w wyniku musi być widoczne Virtualization Enabled In Firmware: Yes.
2. Sprawdź, czy funkcje systemu Windows są włączone:

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

   Stan obu poleceń powinien być Enabled.
3. Sprawdź dostępność WSL: polecenie wsl --version powinno dać prawidłowy wynik; jeśli pojawi się informacja, że polecenie nie istnieje, składniki WSL nie są zainstalowane — wróć do rozdziału 1.
4. Sprawdź możliwość korzystania z WSL 2 (jądro i platforma maszyn wirtualnych): polecenie wsl --set-default-version 2 powinno zwrócić powodzenie. Typowe przyczyny niepowodzenia: nie włączono platformy maszyn wirtualnych lub w BIOS nie włączono VT-x / AMD-V.

3.3 Szybki przegląd typowych przyczyn niepowodzenia

Sytuacja	Opis	Sposób rozwiązania
Wirtualizacja nie włączona w BIOS	Na pewno zakończy się błędem	Zrestartuj komputer, wejdź do BIOS i włącz VT-x / AMD-V (zob. 1.2)
Windows 10 niższy niż 19041	wsl --install nie jest obsługiwany	Zaktualizuj system (zob. 1.1)
Środowisko firmowe wyłącza Hyper-V / wirtualizację	Możliwe niepowodzenie	Skontaktuj się z administratorem systemu
Stara wersja Home systemu	Wymagana instalacja ręczna	Ręcznie zainstaluj jądro WSL zgodnie z 1.4

3.4 Błąd 0xc03a0014: nie można znaleźć dostawcy obsługi dysków wirtualnych

Komunikat błędu: Cannot find a virtual disk support provider for the specified file. Problem nie dotyczy samej dystrybucji systemu Linux, lecz tego, że stos dysków wirtualnych VHD/VHDX w systemie Windows nie działa prawidłowo, przez co WSL 2 nie może zarejestrować dystrybucji ani utworzyć/dołączyć ext4.vhdx.

Najpierw wykonaj minimalną weryfikację: uruchom program PowerShell jako administrator i wykonaj test New-VHD (np. New-VHD -Path C:\test.vhdx -SizeBytes 1GB). Jeśli to polecenie również zgłosi ten sam błąd, problem w 100% leży po stronie systemu Windows i nie ma związku z dystrybucją.

Sprawdzaj i naprawiaj w następującej kolejności:

1. Usługa Virtual Disk nie działa: otwórz services.msc, znajdź usługę Virtual Disk, ustaw typ uruchamiania na "Automatyczny" i uruchom ją.

2. Funkcje WSL / platforma maszyn wirtualnych nie są włączone (lub nie zaczęły działać): ponownie wykonaj polecenia z 1.3 Włączanie powiązanych funkcji Windows, a następnie koniecznie zrestartuj komputer. Wersja Home systemu Windows nie ma pełnego Hyper-V, ale WSL 2 potrzebuje tylko platformy maszyn wirtualnych, a nie konsoli zarządzania Hyper-V.

3. Brak sterowników/urządzeń dysków wirtualnych: otwórz Menedżer urządzeń i sprawdź, czy w sekcji "Urządzenia systemowe / Kontrolery magazynu" znajdują się:

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

   Jeśli ich brakuje, można je dodać ręcznie przez hdwwiz.exe (Kontrolery magazynu → Microsoft → Microsoft VHD Loopback Controller), a także upewnij się, że usługa FsDepends nie jest wyłączona.

4. Importowany obraz nie spełnia wymagań WSL: przy użyciu wsl --import --vhd plik VHDX musi mieć system plików ext4; nie nadają się dyski zaszyfrowane LUKS, zwykłe raw.img, Live ISO ani puste dyski sformatowane w NTFS/FAT. Pliki .img / .qcow2 / .iso nie mogą być bezpośrednio użyte z wsl --import --vhd.

5. Problemy ze ścieżką/uprawnieniami/systemem plików: katalog docelowy musi znajdować się na dysku NTFS (FAT32/exFAT nie są odpowiednie); w ścieżce unikaj polskich znaków, spacji i symboli specjalnych; nie importuj z dysków sieciowych, OneDrive ani skompresowanych folderów; koniecznie używaj prawdziwego programu PowerShell jako administrator (nie zwykłego terminala).

6. Uszkodzone składniki systemu: uruchom kolejno DISM i SFC, aby naprawić składniki systemu, a następnie spróbuj ponownie:

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

TIP

Zewnętrzne maszyny wirtualne (VirtualBox, VMware) lub funkcje piaskownicy/wzmacniania oprogramowania zabezpieczającego (np. 360, Huorong) mogą zakłócać operacje na dyskach wirtualnych; podczas diagnozowania można je tymczasowo wyłączyć i spróbować ponownie.