Setup & Config WSL

WSL Dashboard'ı kullanmadan önce Windows sisteminizde WSL 2 ortamının doğru şekilde etkinleştirilmiş ve yapılandırılmış olması gerekir. Bu belge üç ana bölümden oluşur:

1. WSL'yi Etkinleştirme ve Yapılandırma: WSL 2'nin temel kurulumunu ve yapılandırmasını tamamlayın.
2. Komutun Çalışması Kurulumun Başarılı Olduğu Anlamına Gelmez: wsl komutunun çalıştırılabilir olmasının, Linux'un başarıyla kurulabileceği anlamına gelmediğini açıklar.
3. Kurulum Hatalarını Giderme: Yapılandırma tamamlandıktan sonra kurulumun yine de başarısız olması durumunda kontrol ve onarım yöntemleri.

1. WSL'yi Etkinleştirme ve Yapılandırma

Bu bölüm, gerekli temel ayarları yapmanızda size rehberlik edecektir. Bu bölümü tamamladıktan sonra, komutun çalışması ile başarılı kurulum arasındaki farkı anlamak için 2. bölümü okuyun; kurulumda hâlâ sorun yaşıyorsanız 3. bölüme bakın.

1.1 Sistem Gereksinimlerini Kontrol Etme

WSL 2'nin Windows sürümü için minimum gereksinimleri vardır. Win + R tuşlarına basın, winver yazın ve sürümünüzü kontrol edin:

• Windows 10: Sürüm 1903 veya üzeri, build 18362 veya üzeri olmalıdır.
• Windows 11: Tüm sürümler desteklenir.

IMPORTANT

Sürümünüz çok eskiyse, önce "Windows Update" üzerinden sisteminizi güncelleyin.

1.2 Donanım Sanallaştırmayı Etkinleştirme

WSL 2, sanallaştırma teknolojisi üzerinde çalışır; bu nedenle anakart BIOS/UEFI ayarlarında Sanallaştırma Teknolojisi (Virtualization Technology) etkinleştirilmelidir.

• Kontrol yöntemi: "Görev Yöneticisi"ni (Task Manager) açın → "Performans" (Performance) sekmesi → "CPU".
• Durumu kontrol etme: Sağ alttaki "Sanallaştırma" (Virtualization) durumunun "Etkin" (Enabled) olarak göründüğünden emin olun.
• Etkinleştirme yöntemi: Etkin değilse, bilgisayarı yeniden başlatıp BIOS/UEFI ayarlarına girmeniz, Intel VT-x veya AMD-V gibi bir seçeneği bulup Enabled olarak ayarlamanız gerekir.

1.3 Windows İle İlgili Özellikleri Etkinleştirme

Windows'un "Linux için Windows Alt Sistemi" (Windows Subsystem for Linux) ve "Sanal Makine Platformu" (Virtual Machine Platform) özelliklerini açmanız gerekir.

Yöntem A: Grafik arayüzle (önerilen)

1. Win + S tuşlarına basın, "Windows özelliklerini aç veya kapat" seçeneğini arayıp açın.
2. Aşağıdaki iki öğeyi işaretleyin:
   • Linux için Windows Alt Sistemi (Windows Subsystem for Linux)
   • Sanal Makine Platformu (Virtual Machine Platform)
3. "Tamam"a tıklayın ve istendiğinde bilgisayarı yeniden başlatın.

Yöntem B: Komut satırıyla (yönetici izni)

PowerShell'i yönetici olarak çalıştırın ve aşağıdaki komutları uygulayın:

# WSL'yi etkinleştirin
dism.exe /online /enable-feature /featurename:Microsoft-Windows-Subsystem-Linux /all /norestart

# Sanal Makine Platformunu etkinleştirin
dism.exe /online /enable-feature /featurename:VirtualMachinePlatform /all /norestart

Uygulama tamamlandıktan sonra bilgisayarı elle yeniden başlatın.

1.4 WSL Çekirdeğini Kurma / Güncelleme

Modern Windows sürümleri WSL güncellemelerini Microsoft Store üzerinden alabilir.

• İndirme adresi: Microsoft Store - Windows Subsystem for Linux
• Elle indirme: Mağazayı kullanamıyorsanız, WSL GitHub Releases sayfasından en son .msixbundle veya .msi kurulum paketini indirerek çevrimdışı kurulum yapabilirsiniz.

1.5 WSL 2'yi Varsayılan Sürüm Olarak Ayarlama

Yeni kurulan dağıtımların varsayılan olarak WSL 2 kullandığından emin olmak için terminalde şu komutu çalıştırın:

wsl --set-default-version 2

1.6 Sık Sorulan Sorular

• 0x80370102 hatası: Genellikle BIOS'ta sanallaştırmanın etkinleştirilmemiş olmasından veya Hyper-V ile çakışmadan kaynaklanır.
• WSL 1 ile WSL 2 arasında geçiş: Mevcut bir WSL 1 örneğini WSL 2'ye yükseltmek için wsl --set-version <dağıtım-adı> 2 komutunu kullanabilirsiniz.

2. Komutun Çalışması Kurulumun Başarılı Olduğu Anlamına Gelmez

wsl --version, wsl -l -v gibi komutların sorunsuz çalışabilmesi, Linux kurulumu için gereken koşulların sağlandığı anlamına gelmez. İkisi farklı aşamalardadır ve birbirine eşit tutulamaz.

Komutun çalışması yalnızca şunu gösterir:

• ✅ Windows'ta WSL bileşenleri etkinleştirilmiş / kurulmuştur
• ✅ wsl.exe komut satırı aracı kullanılabilir durumdadır
• ✅ Sistem WSL ile ilgili komutları tanıyabilmektedir

Ancak bir Linux dağıtımını başarıyla kurmak için ek koşulların da sağlanması gerekir. Takılıp kalınan yaygın noktalar şunlardır:

1. Sanallaştırma kapalı: BIOS/UEFI'de VT-x / AMD-V etkinleştirilmemiş; WSL 2 başlatılamıyor veya dağıtım kurulumu sırasında sanallaştırma hatası bildiriliyor (kontrol yöntemi için bkz. 1.2 Donanım Sanallaştırmayı Etkinleştirme).
2. Windows sürümü / build numarası çok eski: WSL 2'nin çekirdek ve sürüm için gereksinimleri vardır; Home sürümü veya çok eski kurumsal görüntülerde özellikler eksik olabilir (kontrol yöntemi için bkz. 1.1 Sistem Gereksinimlerini Kontrol Etme).
3. Linux dağıtımı henüz kurulmamış: wsl -l -v yalnızca kurulu dağıtımları listeler; hiçbir şey kurulmamışsa liste boştur ve bu, Ubuntu'nun doğrudan çalıştırılabileceği anlamına gelmez.
4. Ağ / Microsoft Store sorunları: wsl --install -d <dağıtım> görüntüyü mağazadan veya ağdan çekmeyi gerektirir; şirket ağı, proxy ve güvenlik duvarı bunu engelleyebilir.
5. Yetersiz izinler: Dağıtım kurmak veya WSL ayarlarını değiştirmek için yönetici izni gerekir.

TIP

Kısacası: WSL komutu çalışıyor ≠ Linux hazır; yalnızca "giriş biletini" aldınız, henüz gerçekten bir sistem kurulmadı.

3. Kurulum Hatalarını Giderme

1. bölüm uyarınca yapılandırmayı tamamladıysanız (veya tamamladığınızı düşünüyorsanız) ve wsl --install yine de başarısız oluyorsa, aşağıdaki sırayla kontrol edin.

3.1 Önce "Tek Tıkla Kontrol" Yapın

PowerShell'i yönetici olarak çalıştırın ve sırayla şu komutları uygulayın:

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

• ✅ Bu iki komut da sorunsuz çalışıyorsa, WSL isteğe bağlı bileşenlerinin etkinleştirildiği ve sanallaştırma koşullarının temel olarak sağlandığı anlamına gelir.
• ❌ Başarısız olursa, neyin eksik olduğu doğrudan bildirilir (ör. Sanal Makine Platformu, Hyper-V, BIOS sanallaştırması vb.).

Ardından systeminfo komutunu çalıştırın ve çıktıda Virtualization Enabled In Firmware: Yes ifadesinin göründüğünü doğrulayın. Yukarıdakilerin hiçbirinde hata yoksa, wsl --install ile dağıtımı kurmaya büyük ölçüde güvenle devam edebilirsiniz.

NOTE

Hiçbir komut wsl --install komutunun %100 başarılı olacağını garanti edemez, ancak yukarıdaki kontroller kurulum koşullarının sağlanıp sağlanmadığını doğrulayabilir.

3.2 Elle Kontrol Listesi

"Tek Tıkla Kontrol" sorunu hâlâ belirleyemiyorsa, maddeleri tek tek kontrol edin:

1. BIOS/ürün yazılımı (firmware) sanallaştırmasının açık olup olmadığını kontrol edin: Yönetici PowerShell'de systeminfo çalıştırın; çıktıda Virtualization Enabled In Firmware: Yes görülmelidir.
2. Windows özelliklerinin açık olup olmadığını kontrol edin:

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

   Her iki komutun durumu da Enabled olmalıdır.
3. WSL'nin kullanılabilir olup olmadığını kontrol edin: wsl --version komutunu çalıştırın; normal bir çıktı vermelidir; komutun bulunamadığı belirtiliyorsa WSL bileşenleri kurulmamış demektir; 1. bölüme dönün.
4. WSL 2'nin kullanılıp kullanılamayacağını kontrol edin (çekirdek ve sanal makine platformu): wsl --set-default-version 2 komutu başarıyla dönmelidir. Yaygın başarısızlık nedenleri: sanal makine platformu etkinleştirilmemiş veya BIOS'ta VT-x / AMD-V açılmamış.

3.3 Yaygın Başarısızlık Nedenleri Hızlı Bakış

Durum	Açıklama	Çözüm
BIOS'ta sanallaştırma açık değil	Kesin başarısız	Yeniden başlatıp BIOS'a girin ve VT-x / AMD-V'yi açın (bkz. 1.2)
Windows 10 19041'den düşük	wsl --install desteklenmez	Sistemi güncelleyin (bkz. 1.1)
Kurumsal ortamda Hyper-V / sanallaştırma devre dışı bırakılmış	Başarısız olabilir	Sistem yöneticinizle iletişime geçin
Eski Home sürümü sistem	Elle kurulum gerekir	WSL çekirdeğini 1.4 uyarınca elle kurun

3.4 0xc03a0014 Hatası: Sanal Disk Destek Sağlayıcısı Bulunamıyor

Hata iletisi Cannot find a virtual disk support provider for the specified file şeklindedir. Bu, Linux dağıtımının kendisiyle ilgili bir sorun değil, Windows VHD/VHDX sanal disk yığınının düzgün çalışmamasıdır; WSL 2, dağıtımı kaydederken veya ext4.vhdx oluştururken / bağlarken başarısız olur.

Önce minimum doğrulama yapın: PowerShell'i yönetici olarak çalıştırın ve New-VHD komutunu test edin (ör. New-VHD -Path C:\test.vhdx -SizeBytes 1GB). Bu komut da aynı hatayı bildiriyorsa, sorun %100 Windows tarafındadır ve dağıtımla ilgisi yoktur.

Aşağıdaki sırayla sorunu giderin ve onarın:

1. Virtual Disk hizmeti çalışmıyor: services.msc dosyasını açın, Virtual Disk hizmetini bulun, başlangıç türünü "Otomatik" yapın ve hizmeti başlatın.

2. WSL / sanal makine platformu özellikleri etkinleştirilmemiş (veya etkili olmamış): 1.3 Windows İle İlgili Özellikleri Etkinleştirme bölümündeki komutları yeniden çalıştırın ve ardından mutlaka yeniden başlatın. Windows Home sürümünde tam Hyper-V yoktur, ancak WSL 2 yalnızca sanal makine platformuna ihtiyaç duyar, Hyper-V yönetim arayüzüne değil.

3. Sanal disk sürücüleri / aygıtları eksik: Aygıt Yöneticisi'ni (Device Manager) açın ve "Sistem aygıtları / Depolama denetleyicileri" altında şunların olup olmadığını kontrol edin:

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

   Eksiklerse hdwwiz.exe ile elle eklenebilir (Depolama denetleyicileri → Microsoft → Microsoft VHD Loopback Controller) ve FsDepends hizmetinin devre dışı bırakılmadığından emin olun.

4. İçe aktarılan görüntü WSL gereksinimlerini karşılamıyor: wsl --import --vhd kullanırken VHDX'in dosya sistemi ext4 olmalıdır; LUKS şifreli disk, sıradan raw.img, canlı ISO veya NTFS/FAT biçimlendirilmiş boş disk olamaz. .img / .qcow2 / .iso dosyaları doğrudan wsl --import --vhd ile kullanılamaz.

5. Yol / izin / dosya sistemi sorunları: Hedef dizin NTFS bir diskte olmalıdır (FAT32/exFAT uygun değildir); yolda Çince karakterlerden, boşluklardan ve özel sembollerden kaçının; ağ sürücüsünden, OneDrive'dan veya sıkıştırılmış klasörden içe aktarmayın; mutlaka gerçek bir yönetici PowerShell'i kullanın (sıradan bir terminal değil).

6. Sistem bileşenleri bozuk: Sistem bileşenlerini onarmak için sırasıyla DISM ve SFC komutlarını çalıştırın, ardından yeniden deneyin:

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

TIP

Üçüncü taraf sanallaştırma yazılımları (VirtualBox, VMware) veya güvenlik yazılımlarının sanal alan / güçlendirme özellikleri (360, Huorong gibi) sanal disk işlemlerine müdahale edebilir; sorun giderirken bunları geçici olarak kapatmayı deneyebilirsiniz.