Setup & Config WSL

Bago gamitin ang WSL Dashboard, ang iyong Windows system ay dapat may tamang WSL 2 na naka-enable at naka-configure. Ang dokumentong ito ay nahahati sa tatlong pangunahing bahagi:

1. I-enable at I-configure ang WSL: Kumpletuhin ang pangunahing pag-install at configuration ng WSL 2.
2. Ang Available na Command ay Hindi Nangangahulugang Matagumpay ang Pag-install: Ipinapaliwanag na ang command na wsl ay kayang i-execute ay hindi nangangahulugang maaaring matagumpay na mai-install ang Linux.
3. Pag-troubleshoot sa Nabigong Pag-install: Mga paraan ng pagsuri at pag-aayos kapag nabigo pa rin ang pag-install pagkatapos makumpleto ang configuration.

1. I-enable at I-configure ang WSL

Ang kabanatang ito ay gagabay sa iyo sa pagkumpleto ng mga kinakailangang pangunahing setting. Pagkatapos makumpleto ang kabanatang ito, mangyaring basahin ang Kabanata 2 upang maunawaan ang pagkakaiba sa pagitan ng available na command at matagumpay na pag-install; kung may problema pa rin sa pag-install, sumangguni sa Kabanata 3.

1.1 Suriin ang System Requirements

May minimum na kinakailangan sa Windows version ang WSL 2. I-press ang Win + R, i-type ang winver upang suriin ang iyong bersyon:

• Windows 10: Bersyon 1903 o mas bago, na may Build 18362 o mas mataas.
• Windows 11: Lahat ng bersyon ay sinusuportahan.

IMPORTANT

Kung masyadong mababa ang iyong bersyon, mangyaring i-upgrade muna ang iyong system sa pamamagitan ng "Windows Update".

1.2 I-enable ang Hardware Virtualization

Ang WSL 2 ay tumatakbo batay sa virtualization technology, kaya dapat i-enable ang Virtualization Technology (Teknolohiya ng Virtualization) sa BIOS/UEFI ng motherboard.

• Paraan ng pagsuri: Buksan ang "Task Manager" -> tab na "Performance" -> "CPU".
• Tingnan ang status: Kumpirmahin na ang status na "Virtualization" sa kanang ibaba ay nagpapakita ng "Enabled".
• Paraan ng pag-enable: Kung hindi pa naka-enable, kailangan mong i-restart ang computer upang pumasok sa BIOS/UEFI settings, hanapin ang opsyong katulad ng Intel VT-x o AMD-V at itakda ito sa Enabled.

1.3 I-enable ang mga Windows Feature na Kaugnay

Kailangan mong i-enable ang mga feature na "Windows Subsystem for Linux" at "Virtual Machine Platform" ng Windows.

Paraan A: Sa pamamagitan ng GUI (Inirerekomenda)

1. I-press ang Win + S, hanapin at buksan ang "Turn Windows features on or off".
2. I-check ang sumusunod na dalawang item:
   • Windows Subsystem for Linux (Subsistema ng Windows para sa Linux)
   • Virtual Machine Platform (Platform ng Virtual Machine)
3. I-click ang "OK", at i-restart ang iyong computer kapag na-prompt.

Paraan B: Sa pamamagitan ng Command Line (Administrator)

I-run ang PowerShell bilang Administrator at i-execute ang mga sumusunod na command:

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

# I-enable ang Virtual Machine Platform
dism.exe /online /enable-feature /featurename:VirtualMachinePlatform /all /norestart

Pagkatapos makumpleto, mangyaring i-restart ang iyong computer nang mano-mano.

1.4 I-install / I-update ang WSL Kernel

Ang mga modernong bersyon ng Windows ay maaaring makakuha ng mga WSL update sa pamamagitan ng Microsoft Store.

• Download address: Microsoft Store - Windows Subsystem for Linux
• Manual download: Kung hindi mo magamit ang Store, maaari mong i-download ang pinakabagong .msixbundle o .msi installer mula sa WSL GitHub Releases para sa offline na pag-install.

1.5 Itakda ang WSL 2 bilang Default na Bersyon

Upang matiyak na ang mga bagong na-install na distribusyon ay gumagamit ng WSL 2 bilang default, i-run sa terminal:

wsl --set-default-version 2

1.6 Mga Karaniwang Tanong

• Error 0x80370102: Karaniwang sanhi ito ng hindi naka-enable na virtualization sa BIOS, o may conflict sa Hyper-V.
• Paglipat sa pagitan ng WSL 1 at WSL 2: Maaari mong gamitin ang wsl --set-version <pangalan-ng-distribusyon> 2 upang i-upgrade ang existing na WSL 1 instance sa WSL 2.

2. Ang Available na Command ay Hindi Nangangahulugang Matagumpay ang Pag-install

Ang mga command tulad ng wsl --version, wsl -l -v ay kayang i-execute nang normal, ay hindi nangangahulugang mayroon nang mga kondisyon upang mag-install ng Linux. Magkaiba ang dalawang yugto, hindi maaaring i-equate ang mga ito.

Ang available na command ay nangangahulugan lamang na:

• ✅ Naka-enable/na-install na ang mga WSL component sa Windows
• ✅ Available ang wsl.exe command line tool
• ✅ Nakikilala ng system ang mga command na may kaugnayan sa WSL

Ngunit upang matagumpay na mai-install ang Linux distribution, kailangan pa ring matugunan ang mga karagdagang kondisyon. Ang mga karaniwang nakababagal na lugar:

1. Naka-off ang virtualization: Hindi naka-enable ang VT-x / AMD-V sa BIOS/UEFI, hindi maaaring magsimula ang WSL 2, o nag-uulat ng virtualization error kapag nag-i-install ng distribusyon (tingnan ang paraan ng pagsuri sa 1.2 I-enable ang Hardware Virtualization).
2. Masyadong mababa ang Windows version/build: May kinakailangan ang WSL 2 sa kernel at bersyon, maaaring hindi kumpleto ang mga feature ng Home edition at lumang enterprise image (tingnan ang paraan ng pagsuri sa 1.1 Suriin ang System Requirements).
3. Hindi pa talaga naka-install ang Linux distribution: Inililista lamang ng wsl -l -v ang mga naka-install na distribusyon, kapag wala pang naka-install ay walang laman ang listahan, hindi ito nangangahulugang maaari nang patakbuhin ang Ubuntu.
4. Problema sa network / Microsoft Store: Ang wsl --install -d <distribusyon> ay kailangang kumuha ng image mula sa Store o network, maaaring harangin ito ng company network, proxy, at firewall.
5. Kulang sa pahintulot: Kailangan ng administrator permission upang mag-install ng distribusyon o magbago ng WSL settings.

TIP

Sa madaling salita: ang WSL command ay magagamit ≠ handa na ang Linux, parang nakuha mo lang ang "tiket sa pagpasok", hindi pa talaga naka-install ang system.

3. Pag-troubleshoot sa Nabigong Pag-install

Pagkatapos makumpleto ang configuration ayon sa Kabanata 1 (o sa tingin mo ay nakumpleto mo na ang configuration), kung nabigo pa rin ang wsl --install, mangyaring suriin ayon sa sumusunod na pagkakasunod-sunod.

3.1 Gawin muna ang "One-Click Detection"

I-run ang PowerShell bilang Administrator, i-execute nang sunud-sunod:

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

• ✅ Kung parehong maayos na na-execute ang dalawang command na ito, nangangahulugang naka-enable na ang mga WSL optional component, at karaniwang natutugunan na ang mga kondisyon ng virtualization.
• ❌ Kung nabigo, direktang magsasaad kung ano ang kulang (tulad ng Virtual Machine Platform, Hyper-V, BIOS virtualization, atbp.).

Pagkatapos ay i-run ang systeminfo, at kumpirmahin sa output na lumalabas ang Virtualization Enabled In Firmware: Yes. Kung wala nang error sa itaas, maaari mo nang kalmadong i-run ang wsl --install upang mag-install ng distribusyon.

NOTE

Walang command na makakagarantiya ng 100% na magtatagumpay ang wsl --install, ngunit makukumpirma ng mga pagsusuri sa itaas kung natugunan na ba ang mga kondisyon ng pag-install.

3.2 Manu-manong Checklist sa Pag-detect

Kung hindi pa rin mahanap ng "One-Click Detection" ang problema, maaaring suriin isa-isa:

1. I-detect kung naka-enable ang BIOS/firmware virtualization: Sa Administrator PowerShell i-run ang systeminfo, dapat makita sa output ang Virtualization Enabled In Firmware: Yes.
2. I-detect kung naka-enable na ang mga Windows feature:

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

   Ang status ng parehong command ay dapat Enabled.
3. I-detect kung available ang WSL: I-run ang wsl --version, dapat may normal na output; kung nagpapakita na wala ang command, nangangahulugang hindi pa naka-install ang WSL component, mangyaring bumalik sa Kabanata 1.
4. I-detect kung magagamit ang WSL 2 (kernel & virtual machine platform): I-run ang wsl --set-default-version 2, dapat magtagumpay ang pagbabalik. Mga karaniwang dahilan ng pagkabigo: hindi naka-enable ang Virtual Machine Platform, o hindi naka-enable ang VT-x / AMD-V sa BIOS.

3.3 Mabilisang Sanggunian sa Mga Karaniwang Dahilan ng Pagkabigo

Sitwasyon	Paliwanag	Paraan ng pag-aayos
Hindi naka-enable ang virtualization sa BIOS	Tiyak na mabibigo	I-restart at pumasok sa BIOS upang i-enable ang VT-x / AMD-V (tingnan ang 1.2)
Windows 10 na mas mababa sa 19041	Hindi sinusuportahan ang wsl --install	I-upgrade ang system (tingnan ang 1.1)
Hindi pinapayagan ng enterprise environment ang Hyper-V / virtualization	Maaaring mabigo	Makipag-ugnayan sa system administrator
Lumang Home edition system	Kailangan ng manu-manong pag-install	Manu-manong i-install ang WSL kernel ayon sa 1.4

3.4 Error 0xc03a0014: Hindi Makita ang Virtual Disk Support Provider

Ang error message ay Cannot find a virtual disk support provider for the specified file. Hindi ito problema sa mismong Linux distribution, kundi hindi gumagana nang normal ang VHD/VHDX virtual disk stack ng Windows, nabigo ang WSL 2 kapag nagrerehistro ng distribusyon, gumagawa/nagmo-mount ng ext4.vhdx.

Gawin muna ang minimal na validation: I-run ang PowerShell bilang Administrator, i-execute ang New-VHD test (halimbawa New-VHD -Path C:\test.vhdx -SizeBytes 1GB). Kung ang command na ito ay nag-uulat din ng parehong error, 100% nasa Windows side ang problema, walang kinalaman sa distribusyon.

Suriin at ayusin ayon sa sumusunod na pagkakasunod-sunod:

1. Hindi tumatakbo ang Virtual Disk service: Buksan ang services.msc, hanapin ang Virtual Disk service, itakda ang startup type sa "Automatic" at simulan ito.

2. Hindi naka-enable (o hindi pa epektibo) ang WSL / Virtual Machine Platform feature: I-execute muli ang mga command sa 1.3 I-enable ang mga Windows Feature na Kaugnay, pagkatapos ay dapat mag-restart. Walang kumpletong Hyper-V ang Windows Home edition, ngunit ang WSL 2 ay nangangailangan lamang ng Virtual Machine Platform, hindi ang Hyper-V management interface.

3. Kulang ang virtual disk driver/device: Buksan ang Device Manager, suriin kung mayroon sa "System devices / Storage controllers":

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

   Kapag kulang, maaaring manu-manong idagdag sa pamamagitan ng hdwwiz.exe (Storage controllers → Microsoft → Microsoft VHD Loopback Controller), at kumpirmahin na hindi naka-disable ang FsDepends service.

4. Ang na-import na image ay hindi sumusunod sa WSL requirements: Kapag gumagamit ng wsl --import --vhd, ang VHDX ay dapat na ext4 file system, hindi maaaring LUKS encrypted disk, ordinaryong raw.img, Live ISO, o blangkong disk na naka-format sa NTFS/FAT. Ang .img / .qcow2 / .iso ay hindi maaaring direktang wsl --import --vhd.

5. Problema sa path/pahintulot/file system: Ang target na directory ay dapat nasa NTFS disk (hindi pwede ang FAT32/exFAT); iwasan ang mga Chinese character, espasyo, at espesyal na simbolo sa path; huwag mag-import mula sa network drive, OneDrive, o naka-compress na folder; siguraduhing gumamit ng tunay na Administrator PowerShell (hindi ordinaryong terminal).

6. Nasira ang mga system component: I-run nang sunud-sunod ang DISM at SFC upang ayusin ang mga system component, pagkatapos ay subukan muli:

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

TIP

Ang third-party virtual machine (VirtualBox, VMware) o sandbox/hardening feature ng security software (tulad ng 360, Huorong) ay maaaring makagambala sa virtual disk operations, kapag nag-troubleshoot ay maaaring pansamantalang i-off ang mga ito at subukan muli.