Включение и настройка 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).

• Способ проверки: откройте "Диспетчер задач" -> вкладку "Производительность" -> "CPU".
• Проверка состояния: убедитесь, что статус "Виртуализация" в правом нижнем углу показывает "Включено".
• Способ включения: если она не включена, перезагрузите компьютер, войдите в настройки BIOS/UEFI, найдите параметр, похожий на Intel VT-x или AMD-V, и установите его в значение Enabled.

1.3 Включение связанных функций Windows

Вам необходимо включить функции 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. Виртуализация отключена: в 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) могут мешать работе с виртуальными дисками; при диагностике их можно временно отключить и попробовать снова.