Налаштування 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 Update.

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

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

• Спосіб перевірки: відкрийте "Диспетчер завдань" -> вкладку "Продуктивність" -> "CPU".
• Перевірка стану: переконайтеся, що статус "Віртуалізація" в правому нижньому куті показує "Увімкнено".
• Спосіб увімкнення: якщо вона не увімкнена, перезавантажте комп'ютер, увійдіть у налаштування 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. Натисніть "OK" і перезавантажте комп'ютер після відповідного запиту.

Метод 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. Віртуалізацію вимкнено: у BIOS/UEFI не ввімкнено VT-x / AMD-V, 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/прошивки: у PowerShell від адміністратора виконайте systeminfo; у виводі обов'язково має бути 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) можуть заважати роботі з віртуальними дисками; під час діагностики їх можна тимчасово вимкнути та спробувати знову.