Konfiguracja WSL

Przed użyciem WSL Dashboard w systemie Windows musi być poprawnie włączone i skonfigurowane środowisko WSL 2. Niniejsza dokumentacja składa się z trzech głównych części:

1. Włączanie i konfiguracja WSL: podstawowa instalacja i konfiguracja WSL 2.
2. Dostępność polecenia nie oznacza udanej instalacji: wyjaśnienie, że działające polecenie wsl nie gwarantuje możliwości instalacji Linuksa.
3. Rozwiązywanie problemów z instalacją: sprawdzanie i naprawa problemów, jeśli instalacja nadal nie powiedzie się po konfiguracji.

1. Włączanie i konfiguracja WSL

Ten rozdział przeprowadzi Cię przez niezbędną podstawową konfigurację. Po ukończeniu rozdziału przeczytaj rozdział 2, aby zrozumieć różnicę między dostępnością polecenia a udaną instalacją; jeśli instalacja nadal sprawia problemy, zapoznaj się z rozdziałem 3.

1.1 Sprawdzanie wymagań systemowych

WSL 2 ma minimalne wymagania co do wersji Windows. Naciśnij Win + R, wpisz winver, aby sprawdzić wersję:

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

IMPORTANT

Jeśli Twoja wersja jest za 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 musi być włączona technologia wirtualizacji (Virtualization Technology).

• Jak sprawdzić: otwórz „Menedżer zadań” → zakładkę „Wydajność” → „Procesor”.
• Jak sprawdzić status: upewnij się, że w prawym dolnym rogu status „Wirtualizacja” wyświetla „Włączona”.
• Jak włączyć: jeśli wirtualizacja jest wyłączona, zrestartuj komputer, wejdź do ustawień BIOS/UEFI, znajdź opcję taką jak Intel VT-x lub AMD-V i ustaw ją na Enabled.

1.3 Włączanie odpowiednich funkcji systemu Windows

Należy włączyć funkcje „Podsystem Windows dla Linuksa” oraz „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 Linuksa (Windows Subsystem for Linux)
   • Platforma maszyn wirtualnych (Virtual Machine Platform)
3. Kliknij „OK” i zrestartuj komputer po wyświetleniu monitu.

Metoda B: przez wiersz poleceń (uprawnienia administratora)

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

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

# Włączanie platformy maszyn wirtualnych
dism.exe /online /enable-feature /featurename:VirtualMachinePlatform /all /norestart

Po wykonaniu poleceń ręcznie zrestartuj komputer.

1.4 Instalacja/aktualizacja jądra WSL

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

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

1.5 Ustawienie WSL 2 jako wersji domyślnej

Aby nowo instalowane dystrybucje domyślnie korzystały z WSL 2, wykonaj w terminalu:

wsl --set-default-version 2

1.6 Często zadawane pytania

• Błąd 0x80370102: zwykle oznacza, że wirtualizacja nie jest włączona w BIOS lub występuje konflikt z Hyper-V.
• Przełączanie między WSL 1 i WSL 2: możesz użyć wsl --set-version <nazwa-dystrybucji> 2, aby uaktualnić istniejącą instancję WSL 1 do WSL 2.

2. Dostępność polecenia nie oznacza udanej instalacji

To, że polecenia takie jak wsl --version, wsl -l -v wykonują się poprawnie, nie oznacza, że warunki do instalacji Linuksa są już spełnione. To różne etapy, których nie można zrównywać.

Dostępność polecenia oznacza jedynie, że:

• ✅ Komponenty WSL w systemie Windows są włączone/zainstalowane
• ✅ Narzędzie wiersza poleceń wsl.exe jest dostępne
• ✅ System rozpoznaje polecenia związane z WSL

Ale do udanej instalacji dystrybucji Linuksa potrzebne są dodatkowe warunki. Typowe miejsca utknięcia:

1. Wirtualizacja wyłączona: VT-x / AMD-V nie są włączone w BIOS/UEFI, przez co WSL 2 nie może się uruchomić lub przy instalacji dystrybucji pojawia się błąd wirtualizacji (jak sprawdzić — patrz 1.2 Włączanie wirtualizacji sprzętowej).
2. Za stara wersja/numer kompilacji Windows: WSL 2 ma wymagania co do jądra i wersji; w edycji Home lub zbyt starych obrazach korporacyjnych mogą brakować potrzebnych funkcji (jak sprawdzić — patrz 1.1 Sprawdzanie wymagań systemowych).
3. Dystrybucja Linuksa jeszcze nie zainstalowana: wsl -l -v wyświetla tylko zainstalowane dystrybucje; jeśli nic nie jest zainstalowane, lista będzie pusta — to nie znaczy, że można od razu uruchomić Ubuntu.
4. Problemy z siecią / Microsoft Store: wsl --install -d <dystrybucja> pobiera obrazy ze sklepu lub sieci; sieci firmowe, proxy i zapory mogą blokować pobieranie.
5. Niewystarczające uprawnienia: instalacja dystrybucji lub modyfikacja ustawień WSL wymaga uprawnień administratora.

TIP

Krótko mówiąc: działające polecenia WSL ≠ Linux gotowy — to tylko „bilet wstępu”, a sam system nie jest jeszcze zainstalowany.

3. Rozwiązywanie problemów z instalacją

Jeśli po konfiguracji zgodnie z rozdziałem 1 (lub jeśli uważasz, że już wszystko skonfigurowałeś) polecenie wsl --install nadal kończy się niepowodzeniem, sprawdzaj w podanej kolejności.

3.1 Najpierw „szybka kontrola”

Uruchom PowerShell jako administrator i wykonaj kolejno:

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

• ✅ Jeśli oba polecenia wykonają się pomyślnie, opcjonalne komponenty WSL są włączone, a warunki wirtualizacji w zasadzie spełnione.
• ❌ W razie niepowodzenia system bezpośrednio wskaże, czego brakuje (np. platforma maszyn wirtualnych, Hyper-V, wirtualizacja w BIOS itp.).

Następnie wykonaj systeminfo i potwierdź w wynikach obecność Virtualization Enabled In Firmware: Yes. Jeśli nigdzie nie ma błędów, możesz spokojnie wykonać wsl --install w celu instalacji dystrybucji.

NOTE

Żadne polecenie nie gwarantuje w 100% powodzenia wsl --install, ale opisane kontrole pozwalają potwierdzić, że warunki instalacji są spełnione.

3.2 Ręczna lista kontrolna

Jeśli „szybka kontrola” nie zlokalizowała problemu, sprawdzaj punkt po punkcie:

1. Sprawdzenie wirtualizacji BIOS/oprogramowania układowego: wykonaj systeminfo w PowerShell jako administrator; w wynikach musi znajdować się Virtualization Enabled In Firmware: Yes.
2. Sprawdzenie włączenia funkcji systemu Windows:

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

   Status obu poleceń powinien być Enabled.
3. Sprawdzenie dostępności WSL: wsl --version powinien dać normalny wynik; jeśli system informuje, że polecenia nie znaleziono, komponenty WSL nie są zainstalowane — wróć do rozdziału 1.
4. Sprawdzenie możliwości użycia WSL 2 (jądro i platforma maszyn wirtualnych): wsl --set-default-version 2 powinno zakończyć się sukcesem. Częste 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 niepowodzeń

Sytuacja	Opis	Sposób rozwiązania
Wirtualizacja nie włączona w BIOS	Gwarantowane niepowodzenie	Zrestartuj, wejdź do BIOS i włącz VT-x / AMD-V (patrz 1.2)
Windows 10 niższy niż 19041	Nie obsługuje wsl --install	Zaktualizuj system (patrz 1.1)
W środowisku firmowym wyłączono Hyper-V / wirtualizację	Możliwe niepowodzenie	Skontaktuj się z administratorem systemu
Starsza wersja Home	Wymagana ręczna instalacja	Ręcznie zainstaluj jądro WSL zgodnie z 1.4

3.4 Błąd 0xc03a0014: nie znaleziono dostawcy obsługi wirtualnych dysków

Komunikat błędu: Cannot find a virtual disk support provider for the specified file. To nie jest problem samej dystrybucji Linuksa, lecz nieprawidłowe działanie stosu wirtualnych dysków VHD/VHDX w systemie Windows — WSL 2 nie może zarejestrować dystrybucji ani utworzyć/zmountować ext4.vhdx.

Najpierw minimalna weryfikacja: w PowerShell jako administrator wykonaj test New-VHD (np. New-VHD -Path C:\test.vhdx -SizeBytes 1GB). Jeśli to polecenie również zgłasza ten sam błąd, problem w 100% leży po stronie Windows i nie dotyczy dystrybucji.

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 zadziałały): ponownie wykonaj polecenia z 1.3 Włączanie odpowiednich funkcji systemu Windows, a następnie koniecznie zrestartuj. Edycja 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ń wirtualnych dysków: otwórz Menedżer urządzeń i sprawdź, czy w „Urządzeniach systemowych / Kontrolerach magazynu” znajdują się:

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

   W razie braku można je dodać ręcznie przez hdwwiz.exe (Kontrolery magazynu → Microsoft → Microsoft VHD Loopback Controller) i potwierdzić, że usługa FsDepends nie jest wyłączona.

4. Importowany obraz nie spełnia wymagań WSL: przy użyciu wsl --import --vhd dysk VHDX musi mieć system plików ext4; nie mogą to być woluminy szyfrowane LUKS, zwykłe raw.img, Live ISO ani puste dyski NTFS/FAT. Plików .img / .qcow2 / .iso nie można importować bezpośrednio przez wsl --import --vhd.

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

6. Uszkodzenie komponentów systemu: kolejno uruchom DISM i SFC, aby naprawić komponenty systemu, a następnie spróbuj ponownie:

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

TIP

Maszyny wirtualne innych firm (VirtualBox, VMware) lub funkcje piaskownicy/wzmacniania zabezpieczeń programów antywirusowych (np. 360, Huorong) mogą zakłócać operacje na wirtualnych dyskach — podczas rozwiązywania problemów można je tymczasowo wyłączyć.