Windows Subsystem for Linux Installation Guide for Windows 10

There are two options available for installing Windows Subsystem for Linux (WSL):

Simplified install (preview release): wsl —install

The wsl —install simplified install command requires that you join the Windows Insiders Program and install a preview build of Windows 10 (OS build 20262 or higher), but eliminates the need to follow the manual install steps. All you need to do is open a command window with administrator privileges and run wsl —install , after a restart you will be ready to use WSL.

Manual install: Follow the six steps listed below.

The manual install steps for WSL are listed below and can be used to install Linux on any version of Windows 10.

If you run into an issue during the install process, check the Troubleshooting installation section at the bottom of this page.

Simplified Installation for Windows Insiders

The installation process for Windows Subsystem for Linux has been significantly improved in the latest Windows Insiders preview builds of Windows 10, replacing the manual steps below with a single command.

In order to use the wsl —install simplified install command, you must:

• Join the Windows Insiders Program
• Install a preview build of Windows 10 (OS build 20262 or higher).
• Open a command line windows with Administrator privileges

Once those requirements are met, to install WSL:

• Enter this command in the command line you’ve opened in Admin mode: wsl.exe —install
• Restart your machine

The first time you launch a newly installed Linux distribution, a console window will open and you’ll be asked to wait for files to de-compress and be stored on your PC. All future launches should take less than a second.

CONGRATULATIONS! You’ve successfully installed and set up a Linux distribution that is completely integrated with your Windows operating system!

The —install command performs the following actions:

• Enables the optional WSL and Virtual Machine Platform components
• Downloads and installs the latest Linux kernel
• Sets WSL 2 as the default
• Downloads and installs a Linux distribution (reboot may be required)

By default, the installed Linux distribution will be Ubuntu. This can be changed using wsl —install -d . (Replacing with the name of your desired distribution.) Additional Linux distributions may be added to your machine after the initial install using the wsl —install -d command.

To see a list of available Linux distributions, enter wsl —list —online .

Manual Installation Steps

If you are not on a Windows Insiders build, the features required for WSL will need to be enabled manually following the steps below.

Step 1 — Enable the Windows Subsystem for Linux

You must first enable the «Windows Subsystem for Linux» optional feature before installing any Linux distributions on Windows.

Open PowerShell as Administrator and run:

We recommend now moving on to step #2, updating to WSL 2, but if you wish to only install WSL 1, you can now restart your machine and move on to Step 6 — Install your Linux distribution of choice. To update to WSL 2, wait to restart your machine and move on to the next step.

Step 2 — Check requirements for running WSL 2

To update to WSL 2, you must be running Windows 10.

• For x64 systems: Version 1903 or higher, with Build 18362 or higher.
• For ARM64 systems: Version 2004 or higher, with Build 19041 or higher.
• Builds lower than 18362 do not support WSL 2. Use the Windows Update Assistant to update your version of Windows.

To check your version and build number, select Windows logo key + R, type winver, select OK. Update to the latest Windows version in the Settings menu.

If you are running Windows 10 version 1903 or 1909, open «Settings» from your Windows menu, navigate to «Update & Security» and select «Check for Updates». Your Build number must be 18362.1049+ or 18363.1049+, with the minor build # over .1049. Read more: WSL 2 Support is coming to Windows 10 Versions 1903 and 1909. See the troubleshooting instructions.

Step 3 — Enable Virtual Machine feature

Before installing WSL 2, you must enable the Virtual Machine Platform optional feature. Your machine will require virtualization capabilities to use this feature.

Open PowerShell as Administrator and run:

Restart your machine to complete the WSL install and update to WSL 2.

Step 4 — Download the Linux kernel update package

Download the latest package:

If you’re using an ARM64 machine, please download the ARM64 package instead. If you’re not sure what kind of machine you have, open Command Prompt or PowerShell and enter: systeminfo | find «System Type» . Caveat: On non-English Windows versions, you might have to modify the search text, for example, in German it would be systeminfo | find «Systemtyp» .

Run the update package downloaded in the previous step. (Double-click to run — you will be prompted for elevated permissions, select ‘yes’ to approve this installation.)

Once the installation is complete, move on to the next step — setting WSL 2 as your default version when installing new Linux distributions. (Skip this step if you want your new Linux installs to be set to WSL 1).

Step 5 — Set WSL 2 as your default version

Open PowerShell and run this command to set WSL 2 as the default version when installing a new Linux distribution:

Step 6 — Install your Linux distribution of choice

Open the Microsoft Store and select your favorite Linux distribution.

The following links will open the Microsoft store page for each distribution:

From the distribution’s page, select «Get».

The first time you launch a newly installed Linux distribution, a console window will open and you’ll be asked to wait for a minute or two for files to de-compress and be stored on your PC. All future launches should take less than a second.

CONGRATULATIONS! You’ve successfully installed and set up a Linux distribution that is completely integrated with your Windows operating system!

Install Windows Terminal (optional)

Windows Terminal enables multiple tabs (quickly switch between multiple Linux command lines, Windows Command Prompt, PowerShell, Azure CLI, etc), create custom key bindings (shortcut keys for opening or closing tabs, copy+paste, etc.), use the search feature, and custom themes (color schemes, font styles and sizes, background image/blur/transparency). Learn more.

Set your distribution version to WSL 1 or WSL 2

You can check the WSL version assigned to each of the Linux distributions you have installed by opening the PowerShell command line and entering the command (only available in Windows Build 18362 or higher): wsl -l -v

To set a distribution to be backed by either version of WSL please run:

Make sure to replace with the actual name of your distribution and with the number ‘1’ or ‘2’. You can change back to WSL 1 at anytime by running the same command as above but replacing the ‘2’ with a ‘1’.

The update from WSL 1 to WSL 2 may take several minutes to complete depending on the size of your targeted distribution. If you are running an older (legacy) installation of WSL 1 from Windows 10 Anniversary Update or Creators Update, you may encounter an update error. Follow these instructions to uninstall and remove any legacy distributions.

If wsl —set-default-version results as an invalid command, enter wsl —help . If the —set-default-version is not listed, it means that your OS doesn’t support it and you need to update to version 1903, Build 18362 or higher. If you are on Build 19041 for ARM64, this command may fail when using PowerShell in which case you can use a Command Prompt instead to issue the wsl.exe command.

If you see this message after running the command: WSL 2 requires an update to its kernel component. For information please visit https://aka.ms/wsl2kernel . You still need to install the MSI Linux kernel update package.

Additionally, if you want to make WSL 2 your default architecture you can do so with this command:

This will set the version of any new distribution installed to WSL 2.

Troubleshooting installation

Below are related errors and suggested fixes. Refer to the WSL troubleshooting page for other common errors and their solutions.

Installation failed with error 0x80070003

• The Windows Subsystem for Linux only runs on your system drive (usually this is your C: drive). Make sure that distributions are stored on your system drive:
• Open Settings -> **System —>Storage ->More Storage Settings: Change where new content is saved

WslRegisterDistribution failed with error 0x8007019e

• The Windows Subsystem for Linux optional component is not enabled:
• Open Control Panel ->Programs and Features ->Turn Windows Feature on or off -> Check Windows Subsystem for Linux or using the PowerShell cmdlet mentioned at the beginning of this article.

Installation failed with error 0x80070003 or error 0x80370102

• Please make sure that virtualization is enabled inside of your computer’s BIOS. The instructions on how to do this will vary from computer to computer, and will most likely be under CPU related options.
• WSL2 requires that your CPU supports the Second Level Address Translation (SLAT) feature, which was introduced in Intel Nehalem processors (Intel Core 1st Generation) and AMD Opteron. Older CPUs (such as the Intel Core 2 Duo) will not be able to run WSL2, even if the Virtual Machine Platform is successfully installed.

Error when trying to upgrade: Invalid command line option: wsl —set-version Ubuntu 2

• Enure that you have the Windows Subsystem for Linux enabled, and that you’re using Windows Build version 18362 or higher. To enable WSL run this command in a PowerShell prompt with admin privileges: Enable-WindowsOptionalFeature -Online -FeatureName Microsoft-Windows-Subsystem-Linux .

The requested operation could not be completed due to a virtual disk system limitation. Virtual hard disk files must be uncompressed and unencrypted and must not be sparse.

• Deselect “Compress contents” (as well as “Encrypt contents” if that’s checked) by opening the profile folder for your Linux distribution. It should be located in a folder on your Windows file system, something like: USERPROFILE%\AppData\Local\Packages\CanonicalGroupLimited.
• In this Linux distro profile, there should be a LocalState folder. Right-click this folder to display a menu of options. Select Properties > Advanced and then ensure that the “Compress contents to save disk space” and “Encrypt contents to secure data” checkboxes are unselected (not checked). If you are asked whether to apply this to just to the current folder or to all subfolders and files, select “just this folder” because you are only clearing the compress flag. After this, the wsl —set-version command should work.

In my case, the LocalState folder for my Ubuntu 18.04 distribution was located at C:\Users \AppData\Local\Packages\CanonicalGroupLimited.Ubuntu18.04onWindows_79rhkp1fndgsc

Check WSL Docs GitHub thread #4103 where this issue is being tracked for updated information.

The term ‘wsl’ is not recognized as the name of a cmdlet, function, script file, or operable program.

• Ensure that the Windows Subsystem for Linux Optional Component is installed. Additionally, if you are using an ARM64 device and running this command from PowerShell, you will receive this error. Instead run wsl.exe from PowerShell Core, or Command Prompt.

Error: This update only applies to machines with the Windows Subsystem for Linux.

• To install the Linux kernel update MSI package, WSL is required and should be enabled first. If it fails, it you will see the message: This update only applies to machines with the Windows Subsystem for Linux .
• There are three possible reason you see this message:

You are still in old version of Windows which doesn’t support WSL 2. See step #2 for version requirements and links to update.

WSL is not enabled. You will need to return to step #1 and ensure that the optional WSL feature is enabled on your machine.

After you enabled WSL, a reboot is required for it to take effect, reboot your machine and try again.

Error: WSL 2 requires an update to its kernel component. For information please visit https://aka.ms/wsl2kernel .

• If the Linux kernel package is missing in the %SystemRoot%\system32\lxss\tools folder, you will encounter this error. Resolve it by installing the Linux kernel update MSI package in step #4 of these installation instructions. You may need to uninstall the MSI from ‘Add or Remove Programs’, and install it again.

—>

Взаимодействие Windows с Linux Windows interoperability with Linux

В подсистеме Windows для Linux (WSL) постоянно улучшается интеграция между Windows и Linux. The Windows Subsystem for Linux (WSL) is continuously improving integration between Windows and Linux. Можно сделать следующее. You can:

• Запустить средства Windows (например, notepad.exe) из командной строки Linux (например, Ubuntu). Run Windows tools (ie. notepad.exe) from a Linux command line (ie. Ubuntu).
• Запустить средства Linux (например, grep) из командной строки Windows (например, PowerShell). Run Linux tools (ie. grep) from a Windows command line (ie. PowerShell).
• Совместное использование переменных среды между Linux и Windows. Share environment variables between Linux and Windows. (сборка 17063+) (Build 17063+)

Если вы используете Creators Update (октябрь 2017 г., сборка 16299) или Юбилейное обновление (август 2016 г., сборка 14393), перейдите к более ранним версиям Windows 10. If you’re running Creators Update (Oct 2017, Build 16299) or Anniversary Update (Aug 2016, Build 14393), jump to the Earlier versions of Windows 10.

Запуск инструментов Linux из командной строки Windows Run Linux tools from a Windows command line

Запускайте двоичные файлы Linux из командной строки Windows (CMD или PowerShell), используя wsl (или wsl.exe ). Run Linux binaries from the Windows Command Prompt (CMD) or PowerShell using wsl (or wsl.exe ).

Например: For example:

Двоичные файлы вызываются следующим образом. Binaries invoked in this way:

• Используется тот же рабочий каталог, что и для текущей командной строки или сеанса PowerShell. Use the same working directory as the current CMD or PowerShell prompt.
• Файл выполняется от имени пользователя WSL по умолчанию. Run as the WSL default user.
• Требуются те же права администратора Windows, что и у вызывающего процесса и терминала. Have the same Windows administrative rights as the calling process and terminal.

Команда Linux после wsl (или wsl.exe ) обрабатывается как любая команда, выполняемая в WSL. The Linux command following wsl (or wsl.exe ) is handled like any command run in WSL. Можно выполнять sudo, конвейерную передачу и перенаправление файлов. Things such as sudo, piping, and file redirection work.

Пример использования sudo для обновления дистрибутива Linux по умолчанию: Example using sudo to update your default Linux distribution:

Имя пользователя дистрибутива Linux по умолчанию будет указано после выполнения этой команды, и вам будет предложено указать пароль. Your default Linux distribution user name will be listed after running this command and you will be asked for your password. После правильного ввода пароля дистрибутив скачает обновления. After entering your password correctly, your distribution will download updates.

Смешивание команд Linux и Windows Mixing Linux and Windows commands

Ниже приведено несколько примеров смешиваний команд Linux и Windows с помощью PowerShell. Here are a few examples of mixing Linux and Windows commands using PowerShell.

Чтобы выполнить команду Linux ls -la для вывода списка файлов и команду PowerShell findstr для фильтрации результатов слов, содержащих git, объедините команды: To use the Linux command ls -la to list files and the PowerShell command findstr to filter the results for words containing «git», combine the commands:

Чтобы выполнить команду PowerShell dir для вывода списка файлов и команду Linux grep для фильтрации результатов слов, содержащих git, объедините команды: To use the PowerShell command dir to list files and the Linux command grep to filter the results for words containing «git», combine the commands:

Чтобы использовать команду Linux ls -la для вывода списка файлов и команду PowerShell > out.txt для вывода этого списка в текстовый файл с именем out.txt, объедините команды: To use the Linux command ls -la to list files and the PowerShell command > out.txt to print that list to a text file named «out.txt», combine the commands:

Команды, передаваемые в wsl.exe , перенаправляются в процесс WSL без изменения. The commands passed into wsl.exe are forwarded to the WSL process without modification. Пути к файлам должны быть указаны в формате WSL. File paths must be specified in the WSL format.

Чтобы выполнить команду Linux ls -la для вывода списка файлов в пути файловой системы Linux /proc/cpuinfo с помощью PowerShell, сделайте следующее: To use the Linux command ls -la to list files in the /proc/cpuinfo Linux file system path, using PowerShell:

Чтобы выполнить команду Linux ls -la для вывода списка файлов в пути файловой системы Windows C:\Program Files с помощью PowerShell, сделайте следующее: To use the Linux command ls -la to list files in the C:\Program Files Windows file system path, using PowerShell:

Запуск инструментов Windows из Linux Run Windows tools from Linux

WSL может запускать средства Windows непосредственно из командной строки WSL с помощью [tool-name].exe . WSL can run Windows tools directly from the WSL command line using [tool-name].exe . Например, notepad.exe . For example, notepad.exe .

\’` as the file path.» Currently it I can just enter `notepad.exe foo.txt` and it seems to work fine, so explaining a situation where the file path is needed would be helpful. —>

Приложения, выполняемые таким образом, обладают следующими свойствами. Applications run this way have the following properties:

• Рабочим каталогом остается каталог командной строки WSL (в большинстве случаев; исключения описаны ниже). Retain the working directory as the WSL command prompt (for the most part — exceptions are explained below).
• Они имеют те же разрешения, что и процесс WSL. Have the same permission rights as the WSL process.
• Они выполняются от имени активного пользователя Windows. Run as the active Windows user.
• Они отображаются в диспетчере задач Windows так, как если бы они выполнялись непосредственно из командной строки. Appear in the Windows Task Manager as if directly executed from the CMD prompt.

Исполняемые файлы Windows, выполняемые в WSL, обрабатываются аналогично собственным исполняемым файлам Linux — конвейерной передаче, перенаправлению и даже фоновому режиму работы. Windows executables run in WSL are handled similarly to native Linux executables — piping, redirects, and even backgrounding work as expected.

Чтобы запустить средство Windows ipconfig.exe , использовать средство Linux grep для фильтрации результатов IPv4, а также средство Linux cut для удаления полей столбцов из дистрибутива Linux (например, Ubuntu), введите: To run the Windows tool ipconfig.exe , use the Linux tool grep to filter the «IPv4» results, and use the Linux tool cut to remove the column fields, from a Linux distribution (for example, Ubuntu) enter:

Давайте рассмотрим пример сочетания команд Windows и Linux. Let’s try an example mixing Windows and Linux commands. Откройте дистрибутив Linux (например, Ubuntu) и создайте текстовый файл: touch foo.txt . Open your Linux distribution (ie. Ubuntu) and create a text file: touch foo.txt . Теперь используйте команду Linux ls -la , чтобы отобразить список файлов прямого доступа и сведения об их создании, а также средство Windows PowerShell findstr.exe , чтобы отфильтровать результаты и отобразить только файл foo.txt : Now use the Linux command ls -la to list the direct files and their creation details, plus the Windows PowerShell tool findstr.exe to filter the results so only your foo.txt file shows in the results:

Средства Windows должны иметь расширение файла, его регистр символов должен совпадать с регистром в имени файла и эти файлы должны быть исполняемыми. Windows tools must include the file extension, match the file case, and be executable. Неисполняемые файлы, в том числе сценарии пакетного выполнения и Non-executables including batch scripts. собственные команды командной строки, такие как dir , можно выполнять с помощью команды cmd.exe /C . CMD native commands like dir can be run with cmd.exe /C command.

Например, отобразите список содержимого каталога C:\ файловой системы Windows, введя: For example, list the contents of your Windows files system C:\ directory, by entering:

Или выполните команду ping , чтобы отправить запрос проверки связи на веб-сайт microsoft.com: Or use the ping command to send an echo request to the microsoft.com website:

Параметры передаются в двоичный файл Windows без изменений. Parameters are passed to the Windows binary unmodified. Например, следующая команда откроет C:\temp\foo.txt в notepad.exe . As an example, the following command will open C:\temp\foo.txt in notepad.exe :

Этот способ также будет работать: This will also work:

Совместное использование переменных среды между Windows и WSL Share environment variables between Windows and WSL

Решение WSL и Windows совместно используют WSLENV — специальную переменную среды, созданную для взаимодействия Windows и дистрибутивов Linux, запущенных в WSL. WSL and Windows share a special environment variable, WSLENV , created to bridge Windows and Linux distributions running on WSL.

Свойства переменной WSLENV : Properties of WSLENV variable:

• она используется совместно и существует в средах Windows и WSL; It is shared; it exists in both Windows and WSL environments.
• это список переменных среды, которые совместно используют Windows и WSL; It is a list of environment variables to share between Windows and WSL.
• она позволяет форматировать список переменных среды для корректного использования в Windows и WSL. It can format environment variables to work well in Windows and WSL.
• она может использоваться в потоке между WSL и Win32. It can assist in the flow between WSL and Win32.

До выпуска сборки 17063 единственной переменной среды Windows,, к которой могла получить доступ WSL, была PATH (это позволяло запускать исполняемые файлы Win32 из WSL). Prior to 17063, only Windows environment variable that WSL could access was PATH (so you could launch Win32 executables from under WSL). Начиная со сборки 17063, WSLENV поддерживается. Starting in 17063, WSLENV begins being supported. WSLENV учитывает регистр. WSLENV is case sensitive.

Флаги WSLENV WSLENV flags

В WSLENV доступны четыре флага, влияющие на способ преобразования переменной среды. There are four flags available in WSLENV to influence how the environment variable is translated.

Флаги WSLENV : WSLENV flags:

• /p преобразовывает пути WSL и Linux в пути Win32 и наоборот; /p — translates the path between WSL/Linux style paths and Win32 paths.
• /l указывает, что переменная среды представляет собой список путей; /l — indicates the environment variable is a list of paths.
• /u указывает, что эту переменную среды следует добавлять только при запуске WSL из Win32; /u — indicates that this environment variable should only be included when running WSL from Win32.
• /w указывает, что эту переменную среды следует добавлять только при запуске Win32 из WSL. /w — indicates that this environment variable should only be included when running Win32 from WSL.

При необходимости флаги можно комбинировать. Flags can be combined as needed.

Узнайте больше о WSLENV, ознакомившись с часто задаваемыми вопросами и примерами установки значения WSLENV для объединения других предварительно определенных переменных среды с суффиксом в виде косой чертой и флагами для указания способа перевода значения и передачи переменных скрипту. Read more about WSLENV, including FAQs and examples of setting the value of WSLENV to a concatenation of other pre-defined environment vars, each suffixed with a slash followed by flags to specify how the value should be translated and passing variables with a script. В этой статье также показано, как настроить среду разработки с помощью языка программирования Go для совместного использования GOPATH с WSL и Win32. This article also includes an example for setting up a dev environment with the Go programming language, configured to share a GOPATH between WSL and Win32.

Отключение взаимодействия Disable interoperability

Пользователи могут отключить возможность запуска средств Windows для отдельного сеанса WSL, выполнив следующую команду в качестве привилегированного пользователя. Users may disable the ability to run Windows tools for a single WSL session by running the following command as root:

Чтобы повторно включить возможность запуска двоичных файлов Windows, закройте все сеансы WSL и повторно запустите bash.exe или выполните следующую команду от имени привилегированного пользователя. To re-enable Windows binaries, exit all WSL sessions and re-run bash.exe or run the following command as root:

Отключение взаимодействия не будет сохраняться между сеансами WSL, оно снова будет включено при запуске нового сеанса. Disabling interop will not persist between WSL sessions — interop will be enabled again when a new session is launched.

Предшествующие версии Windows 10 Earlier versions of Windows 10

В предшествующих версиях Windows 10 для команд взаимодействия существует несколько различий. There are several differences for the interoperability commands on earlier Windows 10 versions. Если вы используете версию Creators Update (октябрь 2017 г., сборка 16299) или Юбилейного обновления (август 2016 г., сборка 14393) Windows 10, мы рекомендуем выполнить обновление до последней версии Windows. Если это невозможно, мы выделили некоторые отличия при взаимодействии ниже. If you’re running a Creators Update (Oct 2017, Build 16299), or Anniversary Update (Aug 2016, Build 14393) version of Windows 10, we recommend you update to the latest Windows version, but if that’s not possible, we have outlined some of the interop differences below.

• bash.exe заменен на wsl.exe ; bash.exe has been replaced with wsl.exe .
• параметр -c не требуется для выполнения одной команды wsl.exe ; -c option for running a single command isn’t needed with wsl.exe .
• путь Windows включен в переменную $PATH WSL. Windows path is included in the WSL $PATH .
• Процесс отключения взаимодействия не изменяется. The process for disabling interop is unchanged.

Команды Linux можно запускать из командной строки Windows или из PowerShell, но для ранних версий Windows необходимо использовать команду bash . Linux commands can be run from the Windows Command Prompt or from PowerShell, but for early Windows versions, you man need to use the bash command. Например: For example:

Такие функции, как ввод, конвейерная передача и перенаправление файлов, работают должным образом. Things such as input, piping, and file redirection work as expected.

Команды WSL, передаваемые в bash -c , перенаправляются в процесс WSL без изменения. The WSL commands passed into bash -c are forwarded to the WSL process without modification. Пути к файлам должны быть указаны в формате WSL, кроме того, необходимо внимательно экранировать соответствующие знаки. File paths must be specified in the WSL format and care must be taken to escape relevant characters. Пример: Example:

При вызове средства Windows из дистрибутива WSL в ранних версиях Windows 10 необходимо указать путь к каталогу. When calling a Windows tool from a WSL distribution in an earlier version of Windows 10, you will need to specify the directory path. Например, в командной строке WSL введите: For example, from your WSL command line, enter:

В WSL эти исполняемые файлы обрабатываются аналогично собственным исполняемым файлам Linux. In WSL, these executables are handled similar to native Linux executables. Это означает, что добавление каталогов в путь Linux и их конвейерная передача между командами выполняется должным образом. This means adding directories to the Linux path and piping between commands works as expected. Например: For example:

Читайте также:  Восстановление рабочий стол windows 10