WSL: как установить дистрибутив из .wsl файла

Что такое .wsl и чем он отличается от tar

Microsoft описывает .wsl как современный пакет дистрибутива, основанный на tar root filesystem и метаданных дистрибутива. Такой пакет можно установить командой --from-file, а при корректно подготовленной конфигурации — также открыть двойным щелчком в Проводнике. Это отличается от классического wsl --import, где пользователь сам задаёт имя, папку установки и путь к tar или VHDX. Для готового .wsl файла логика ближе к установочному пакету: автор дистрибутива может заранее задать метаданные и поведение первого запуска. Не переименовывайте произвольный архив в .wsl и не ожидайте, что он автоматически станет валидным пакетом. Microsoft отдельно описывает требования к rootfs и /etc/wsl-distribution.conf. Если файл получен от команды разработчиков или официального поставщика, проверьте хэш и происхождение до установки, потому что дистрибутив получает доступ к пользовательской среде.

Совет: Если вам дали обычный rootfs.tar, используйте wsl --import. --from-file рассчитан именно на подготовленный .wsl пакет.

Как установить .wsl пакет по шагам

1. Проверьте WSL: В PowerShell выполните wsl --version; при необходимости обновите через wsl --update.
2. Проверьте файл: Убедитесь, что .wsl полностью скачан, путь корректен, а хэш совпадает с источником.
3. Запустите установку: Выполните wsl --install --from-file "C:\Downloads\mydistro.wsl".
4. Проверьте регистрацию: Выполните wsl --list --verbose и найдите новый дистрибутив.
5. Запустите первый вход: Откройте его через wsl -d <ИмяДистрибутива> и завершите первоначальную настройку.

Что делать, если --from-file не распознаётся

Первая проверка при неизвестной опции — версия WSL, а не версия Ubuntu внутри дистрибутива. Поддержка современного .wsl формата добавлена в новых выпусках WSL, поэтому старый inbox-компонент Windows может не знать параметр --from-file. Выполните wsl --version и wsl --help, затем обновите WSL через wsl --update и повторно откройте PowerShell. Если корпоративная политика блокирует Store-версию WSL или обновления, не скачивайте случайные бинарники для обхода ограничений. Ошибка при распаковке либо первом запуске может означать повреждённую загрузку или дефект самого пакета. Сравните SHA-256 с опубликованным поставщиком и запросите новый файл, прежде чем пытаться вручную исправлять rootfs. Для обычного rootfs.tar используйте wsl --import: это другой, документированный сценарий.

Важно: Не устанавливайте неизвестные .wsl файлы из случайных источников: внутри полноценная Linux-среда.

Когда использовать --from-file, --import и обычный install

• Готовый пакет .wsl. wsl --install --from-file <file>. Путь к пакету
• Rootfs .tar. wsl --import <Name> <Location> <File>. Имя и каталог
• Дистрибутив из каталога. wsl --install -d <Name>. Имя из online list
• Готовый ext4 VHDX. wsl --import-in-place <Name> <File>. Имя и VHDX

Как проверить пакет до первого запуска

Для внутреннего пакета удобно хранить рядом номер сборки, SHA-256 и минимальную версию WSL. Тогда одинаковое имя файла не скрывает различия между релизами. После установки не предполагайте, что зарегистрированное имя совпадает с именем файла: пакет может содержать собственные FriendlyName и defaultName. Сначала выполните wsl -l -v, затем запускайте через wsl -d <Имя>. Если дистрибутив предназначен для разработки, не делайте его default до проверки shell, пользователя, сетевого доступа и монтирования Windows-дисков. Если команда распространяет собственный .wsl в CI или корпоративном образе, фиксируйте версию WSL и хэш пакета в автоматизации. Это позволяет отличить проблему пакета от изменений WSL на хосте и воспроизводить установку на нескольких машинах.

Что проверить после установки

• wsl --list --verbose показывает новый дистрибутив
• Запуск wsl -d <имя> проходит без ошибки регистрации
• Внутри есть ожидаемый /etc/os-release
• Пользователь по умолчанию соответствует документации
• Хэш исходного .wsl сохранён
• Для тестового пакета не затронуты рабочие дистрибутивы

Предупреждение: Не выполняйте unregister рабочего дистрибутива ради эксперимента — это удалит его данные.

Как удалить неудачную установку без потери нужных данных

Сначала узнайте точное зарегистрированное имя через wsl -l -v. Если тестовый дистрибутив больше не нужен, wsl --unregister <Name> удаляет его регистрацию вместе с данными, настройками и установленными пакетами; Microsoft прямо предупреждает, что это необратимо. Поэтому не используйте unregister как «перезапуск установки», пока внутри есть нужные файлы. Если требуется сохранить состояние, сначала экспортируйте дистрибутив или скопируйте данные в безопасное место. Исходный .wsl файл остаётся отдельным артефактом, но установленная Linux-среда удаляется. После очистки можно повторить --from-file с исправленным пакетом. Для обновления рабочего окружения лучше иметь план миграции, чем ставить новый пакет поверх старого вслепую.

Как встроить .wsl в повторяемый рабочий процесс

Если .wsl используется не разово, а как артефакт команды, относитесь к нему как к установочному образу. Храните номер версии, SHA-256, дату сборки и минимально поддерживаемый WSL рядом с файлом или в release notes. Перед массовой установкой проверьте пакет на отдельной машине: корректно ли создаётся пользователь, запускается ли shell, доступны ли сетевые функции и Windows-диски. Если новый пакет должен заменить старую рабочую среду, сначала экспортируйте данные и определите, какие каталоги переносятся, а какие создаются заново. Не полагайтесь на одинаковое имя файла как на доказательство одинакового содержимого. В автоматизации после --from-file полезно проверять wsl -l -q и фактическое имя дистрибутива, потому что оно задаётся метаданными пакета. Так установка становится воспроизводимой и не превращается в ручное угадывание.

Что зафиксировать после успешной установки

Сохраните точное зарегистрированное имя из wsl -l -v, версию WSL и SHA-256 исходного .wsl файла. Если пакет ставится на нескольких компьютерах, эти три значения позволяют быстро понять, одинаковый ли артефакт и одинаковая ли версия WSL использовались. Это полезнее, чем ориентироваться только на имя скачанного файла.

Что учитывать

Условия меняются. Страница отражает состояние на 2026-09-21; при расхождении с официальной документацией приоритет у первоисточника.

Источники и проверка

Фактическая часть сверена по первичным источникам (в т.ч. Build a Custom Linux Distribution for WSL). Пример и формулировки — редакция N1RO на 2026-09-21.

• Build a Custom Linux Distribution for WSL
• Basic commands for WSL