Настройка 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) могут мешать работе с виртуальными дисками — при поиске неполадок их можно временно отключить.