Налаштування WSL

Перед використанням WSL Dashboard на вашій системі Windows має бути правильно ввімкнено та налаштовано середовище WSL 2. Ця документація складається з трьох основних частин:

1. Увімкнення та налаштування WSL: базова установка та налаштування WSL 2.
2. Доступність команди не означає успішну установку: пояснення того, що робоча команда wsl не гарантує можливість установки Linux.
3. Усунення неполадок установки: перевірка та виправлення проблем, якщо установка все ще не вдається після налаштування.

1. Увімкнення та налаштування WSL

Ця глава допоможе вам виконати необхідне базове налаштування. Після завершення глави прочитайте главу 2, щоб зрозуміти різницю між доступністю команди та успішною установкою; якщо установка все ще викликає проблеми, зверніться до глави 3.

1.1 Перевірка системних вимог

WSL 2 висуває мінімальні вимоги до версії Windows. Натисніть Win + R, введіть winver, щоб перевірити версію:

• Windows 10: версія 1903 або новіша, номер збірки (Build) має бути 18362 або новішим.
• Windows 11: підтримуються всі версії.

IMPORTANT

Якщо ваша версія занадто стара, спочатку оновіть систему через «Центр оновлення Windows».

1.2 Увімкнення апаратної віртуалізації

WSL 2 працює на основі технології віртуалізації, тому в BIOS/UEFI материнської плати має бути ввімкнена технологія віртуалізації (Virtualization Technology).

• Як перевірити: відкрийте «Диспетчер завдань» → вкладку «Продуктивність» → «ЦП».
• Як подивитися статус: переконайтеся, що в правому нижньому куті статус «Віртуалізація» відображається як «Увімкнено».
• Як увімкнути: якщо віртуалізацію вимкнено, перезавантажте комп'ютер, увійдіть у налаштування BIOS/UEFI, знайдіть опцію на кшталт Intel VT-x або AMD-V та встановіть значення Enabled.

1.3 Увімкнення відповідних компонентів Windows

Вам потрібно ввімкнути компоненти «Підсистема Windows для Linux» та «Платформа віртуальних машин».

Спосіб A: через графічний інтерфейс (рекомендується)

1. Натисніть Win + S, знайдіть та відкрийте «Увімкнення або вимкнення компонентів Windows».
2. Позначте наступні два пункти:
   • Підсистема Windows для Linux (Windows Subsystem for Linux)
   • Платформа віртуальних машин (Virtual Machine Platform)
3. Натисніть «ОК» та перезавантажте комп'ютер при появі запиту.

Спосіб B: через командний рядок (права адміністратора)

Запустіть PowerShell від імені адміністратора та виконайте наступні команди:

# Увімкнення WSL
dism.exe /online /enable-feature /featurename:Microsoft-Windows-Subsystem-Linux /all /norestart

# Увімкнення платформи віртуальних машин
dism.exe /online /enable-feature /featurename:VirtualMachinePlatform /all /norestart

Після виконання команд вручну перезавантажте комп'ютер.

1.4 Встановлення/оновлення ядра WSL

Сучасні версії Windows можуть отримувати оновлення WSL через Microsoft Store.

• Адреса завантаження: Microsoft Store — Windows Subsystem for Linux
• Ручне завантаження: якщо магазин недоступний, можна завантажити останній пакет .msixbundle або .msi для автономного встановлення зі сторінки WSL GitHub Releases.

1.5 Встановлення WSL 2 як версії за замовчуванням

Щоб нові дистрибутиви за замовчуванням використовували WSL 2, виконайте в терміналі:

wsl --set-default-version 2

1.6 Поширені запитання

• Помилка 0x80370102: зазвичай означає, що віртуалізацію не ввімкнено в BIOS або є конфлікт із Hyper-V.
• Перемикання між WSL 1 і WSL 2: ви можете використовувати wsl --set-version <ім'я-дистрибутива> 2, щоб оновити наявний екземпляр WSL 1 до WSL 2.

2. Доступність команди не означає успішну установку

Те, що команди wsl --version, wsl -l -v тощо виконуються коректно, не означає, що умови для встановлення Linux уже готові. Це різні етапи, і їх не можна прирівнювати.

Доступність команди означає лише те, що:

• ✅ Компоненти WSL у Windows увімкнено/встановлено
• ✅ Інструмент командного рядка wsl.exe доступний
• ✅ Система розпізнає команди, пов'язані з WSL

Але для успішного встановлення дистрибутива Linux потрібні додаткові умови. Часті точки застрягання:

1. Віртуалізацію вимкнено: VT-x / AMD-V не ввімкнено в BIOS/UEFI, через що WSL 2 не може запуститися або при встановленні дистрибутива виникає помилка віртуалізації (як перевірити — див. 1.2 Увімкнення апаратної віртуалізації).
2. Занадто стара версія/номер збірки Windows: WSL 2 висуває вимоги до ядра та версії; у домашній редакції або занадто старих корпоративних образах можуть бути відсутні потрібні функції (як перевірити — див. 1.1 Перевірка системних вимог).
3. Дистрибутив Linux ще не встановлено: wsl -l -v показує лише встановлені дистрибутиви; якщо нічого не встановлено, список буде порожнім — це не означає, що можна одразу запустити Ubuntu.
4. Проблеми з мережею / Microsoft Store: wsl --install -d <дистрибутив> завантажує образи з магазину або мережі; корпоративні мережі, проксі та брандмауери можуть блокувати завантаження.
5. Недостатньо прав: встановлення дистрибутивів або зміна налаштувань WSL вимагають прав адміністратора.

TIP

Простіше кажучи: робочі команди WSL ≠ Linux готовий — це лише «вхідний квиток», а сама система ще не встановлена.

3. Усунення неполадок установки

Якщо після налаштування за главою 1 (або якщо ви вважаєте, що вже все налаштували) команда wsl --install все ще завершується невдачею, перевіряйте в зазначеному порядку.

3.1 Спочатку «швидка перевірка»

Запустіть PowerShell від імені адміністратора та виконайте по черзі:

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

• ✅ Якщо обидві команди виконалися без помилок, додаткові компоненти WSL увімкнено та умови віртуалізації загалом виконано.
• ❌ При збої система безпосередньо вкаже, чого не вистачає (наприклад, платформа віртуальних машин, Hyper-V, віртуалізація в BIOS тощо).

Потім виконайте systeminfo і переконайтеся, що у виводі присутній рядок Virtualization Enabled In Firmware: Yes. Якщо помилок немає ніде, можна спокійно виконувати wsl --install для встановлення дистрибутива.

NOTE

Жодна команда не гарантує на 100% успіх wsl --install, але описані перевірки дозволяють переконатися, що умови встановлення виконано.

3.2 Ручний контрольний список

Якщо «швидка перевірка» не виявила проблему, перевіряйте за пунктами:

1. Перевірка ввімкнення віртуалізації в BIOS/прошивці: виконайте systeminfo у PowerShell від імені адміністратора; у виводі обов'язково має бути рядок Virtualization Enabled In Firmware: Yes.
2. Перевірка ввімкнення компонентів Windows:

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

   Статус обох команд має бути Enabled.
3. Перевірка доступності WSL: wsl --version має давати нормальний вивід; якщо система повідомляє, що команду не знайдено, компоненти WSL не встановлено — поверніться до глави 1.
4. Перевірка можливості використання WSL 2 (ядро та платформа віртуальних машин): wsl --set-default-version 2 має завершитися успішно. Часті причини збою: не ввімкнено платформу віртуальних машин або в BIOS не ввімкнено VT-x / AMD-V.

3.3 Часті причини збоїв

Ситуація	Опис	Рішення
Віртуалізацію не ввімкнено в BIOS	Гарантований збій	Перезавантажтеся, увійдіть у BIOS і ввімкніть VT-x / AMD-V (див. 1.2)
Windows 10 нижче версії 19041	Не підтримується wsl --install	Оновіть систему (див. 1.1)
У корпоративному середовищі вимкнено Hyper-V / віртуалізацію	Можливий збій	Зверніться до системного адміністратора
Застаріла домашня редакція	Потрібне ручне встановлення	Вручну встановіть ядро WSL за 1.4

3.4 Помилка 0xc03a0014: не знайдено постачальника підтримки віртуальних дисків

Повідомлення про помилку: Cannot find a virtual disk support provider for the specified file. Це не проблема самого дистрибутива Linux, а збій у роботі стека віртуальних дисків VHD/VHDX Windows — WSL 2 не може зареєструвати дистрибутив або створити/змонтувати ext4.vhdx.

Спочатку мінімальна перевірка: у PowerShell від імені адміністратора виконайте тест New-VHD (наприклад, New-VHD -Path C:\test.vhdx -SizeBytes 1GB). Якщо ця команда також повідомляє ту саму помилку, проблема на 100% на боці Windows і не пов'язана з дистрибутивом.

Усувайте в наступному порядку:

1. Службу Virtual Disk не запущено: відкрийте services.msc, знайдіть службу Virtual Disk, встановіть тип запуску «Автоматично» та запустіть її.

2. Компоненти WSL / платформу віртуальних машин не ввімкнено (або не застосувалися): повторно виконайте команди з 1.3 Увімкнення відповідних компонентів Windows, потім обов'язково перезавантажтеся. У домашній редакції Windows немає повного Hyper-V, але WSL 2 потрібна лише платформа віртуальних машин, а не консоль керування Hyper-V.

3. Відсутні драйвери/пристрої віртуальних дисків: відкрийте диспетчер пристроїв і перевірте наявність у «Системних пристроях / Контролерах сховища»:

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

   При відсутності можна додати вручну через hdwwiz.exe (Контролери сховища → Microsoft → Microsoft VHD Loopback Controller) і переконатися, що службу FsDepends не вимкнено.

4. Імпортований образ не відповідає вимогам WSL: при використанні wsl --import --vhd VHDX має мати файлову систему ext4; не можна використовувати зашифровані томи LUKS, звичайні raw.img, Live ISO або порожні диски NTFS/FAT. Файли .img / .qcow2 / .iso не можна імпортувати безпосередньо через wsl --import --vhd.

5. Проблеми зі шляхом/правами/файловою системою: цільовий каталог має знаходитися на диску NTFS (FAT32/exFAT не підійдуть); уникайте китайських символів, пробілів і спецсимволів у шляху; не імпортуйте з мережевих дисків, OneDrive або зі стиснених папок; обов'язково використовуйте справжній PowerShell від імені адміністратора (а не звичайний термінал).

6. Пошкодження системних компонентів: послідовно виконайте DISM і SFC для відновлення системних компонентів, потім повторіть спробу:

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

TIP

Сторонні віртуальні машини (VirtualBox, VMware) або пісочниця/функції посилення захисту антивірусів (наприклад, 360, Huorong) можуть заважати роботі з віртуальними дисками — під час пошуку неполадок їх можна тимчасово вимкнути.