Frequently Asked Questions about Windows Subsystem for Linux

The Windows Subsystem for Linux (WSL) is a feature of the Windows operating system that enables you to run a Linux file system, along with Linux command-line tools and GUI apps, directly on Windows, alongside your traditional Windows desktop and apps.

See the about page for more details.

This is primarily a tool for developers, especially web developers, those working on open source projects, or deploying to Linux server environments. WSL is for anyone who likes using Bash, common Linux tools (sed, awk, etc.) and Linux-first frameworks (Ruby, Python, etc.) but also enjoys using Windows productivity tools.

WSL enables you to run Linux in a Bash shell with your choice of distribution (Ubuntu, Debian, OpenSUSE, Kali, Alpine, etc). Using Bash, you can run command-line Linux tools and apps. For example, type lsb_release -a and hit enter; you’ll see details of the Linux distro currently running:

You can also access your local machine’s file system from within the Linux Bash shell – you’ll find your local drives mounted under the /mnt folder. For example, your C: drive is mounted under /mnt/c:

WSL targets a developer audience with the intent to be used as part of an inner development loop. Let's say that Sam is creating a CI/CD pipeline (Continuous Integration & Continuous Delivery) and wants to test it first on a local machine (laptop) before deploying it to the cloud. Sam can enable WSL (& WSL 2 to improve speed and performance), and then use a genuine Linux Ubuntu instance locally (on the laptop) with whatever Bash commands and tools they prefer. Once the development pipeline is verified locally, Sam can then push that CI/CD pipeline up to the cloud (i.e. Azure) by making it into a Docker container and pushing the container to a cloud instance where it runs on a production-ready Ubuntu VM.

Bash is a popular text-based shell and command-language. It is the default shell included within Ubuntu and other Linux distros. Users type commands into a shell to execute scripts and/or run commands and tools to accomplish many tasks.

Check out this article on the Windows Command Line blog: A Deep Dive Into How WSL Allows Windows to Access Linux Files which goes into detail about the underlying technology.

WSL requires fewer resources (CPU, memory, and storage) than a full virtual machine. WSL also allows you to run Linux command-line tools and apps alongside your Windows command-line, desktop and store apps, and to access your Windows files from within Linux. This enables you to use Windows apps and Linux command-line tools on the same set of files if you wish.

Some cross-platform tools were built assuming that the environment in which they run behaves like Linux. For example, some tools assume that they are able to access very long file paths or that specific files/folders exist. This often causes problems on Windows which often behaves differently from Linux.

Many languages like Ruby and Node.js are often ported to, and run great, on Windows. However, not all of the Ruby Gem or node/NPM library owners port their libraries to support Windows, and many have Linux-specific dependencies. This can often result in systems built using such tools and libraries suffering from build and sometimes runtime errors or unwanted behaviors on Windows.

These are just some of issues that caused many people to ask Microsoft to improve Windows’ command-line tools and what drove us to partner with Canonical to enable native Bash and Linux command-line tools to run on Windows.

While working with OSS projects, there are numerous scenarios where it’s immensely useful to drop into Bash from a PowerShell prompt. Bash support is complementary and strengthens the value of the command-line on Windows, allowing PowerShell and the PowerShell community to leverage other popular technologies.

Read more on the PowerShell team blog -- Bash for Windows: Why it’s awesome and what it means for PowerShell

WSL supports x64 and Arm CPUs.

Mount points for hard drives on the local machine are automatically created and provide easy access to the Windows file system.

/mnt/<drive letter>/

Example usage would be cd /mnt/c to access c:\

See the tutorial Get started using Git on Windows Subsystem for Linux, which features a section on setting up Git Credential Manager and storing authentication tokens in Windows Credential Manager.

One of the benefits of WSL is being able to access your files via both Windows and Linux apps or tools.

WSL mounts your machine's fixed drives under the /mnt/<drive> folder in your Linux distros. For example, your C: drive is mounted under /mnt/c/.

Using your mounted drives, you can edit code in, for example, C:\dev\myproj\ using Visual Studio or VS Code, and build/test that code in Linux by accessing the same files via /mnt/c/dev/myproj.

Learn more in Working across Windows and Linux file systems article.

1. Files under the Linux root (i.e. /) are controlled by WSL which aligns with Linux behavior, including but not limited to:

   • Files which contain invalid Windows filename characters
   • Symlinks created for non-admin users
   • Changing file attributes through chmod and chown
   • File/folder case sensitivity

2. Files in mounted drives are controlled by Windows and have the following behaviors:

   • Support case sensitivity
   • All permissions are set to best reflect the Windows permissions

To remove a distribution from WSL and delete all of the data associated with that Linux distribution, run wsl --unregister <distroName> where <distroName> is the name of your Linux distro, which can be seen from the list in the wsl -l command.

Additionally, you can then uninstall the Linux distro app on your machine just like any other store application.

To learn more about wsl commands, see the article, Basic commands for WSL.

OpenSSH ships with Windows as an optional feature. See the Install OpenSSH doc. Administrator privileges in Windows are required to run OpenSSH in WSL. To run an OpenSSH server, run your WSL distribution (i.e. Ubuntu) or Windows Terminal as an administrator. There are several resources out there covering SSH scenarios with WSL. Check out Scott Hanselman's blog articles: How to SSH into a Windows 10 Machine from Linux OR Windows OR anywhere, How to SSH into WSL2 on Windows 10 from an external machine, THE EASY WAY how to SSH into Bash and WSL2 on Windows 10 from an external machine, and How to use Windows 10's built-in OpenSSH to automatically SSH into a remote Linux machine.

WSL install will try to automatically change the Ubuntu locale to match the locale of your Windows install. If you do not want this behavior you can run this command to change the Ubuntu locale after install completes. You will have to relaunch your WSL distribution for this change to take effect.

The below example changes the locale to en-US:

sudo update-locale LANG=en_US.UTF8

Some users have reported issues with specific firewall applications blocking internet access in WSL. The firewalls reported are:

1. Kaspersky
2. AVG
3. Avast
4. Symantec Endpoint Protection
5. F-Secure

In some cases turning off the firewall allows for access. In some cases simply having the firewall installed looks to block access.

WSL shares the IP address of Windows, as it is running on Windows. As such you can access any ports on localhost e.g. if you had web content on port 1234 you could https://localhost:1234 into your Windows browser. For more information, see Accessing network applications.

The best way to backup or move your distributions is via the export/import commands available in Windows Version 1809 and later. You can export your entire distribution to a tarball using the wsl --export command. You can then import this distribution back into WSL using the wsl --import command, which can name a new drive location for the import, allowing you to backup and save states of (or move) your WSL distributions. To learn more about moving your WSL distributions, see How can I transfer my WSL files from one machine to another?.

Traditional backup services that backup files in your AppData folders (like Windows Backup) will not corrupt your Linux files.

Yes, however WSL has been designed and built to use with inner loop development workflows. There are design features in WSL that make it great for this purpose but may make it challenging for production-related scenarios compared to other products. Our goal is to make clear how WSL differs from a regular VM environment, so you can make the decision on whether it fits your business needs.

The main differences between WSL and a traditional production environment are:

• WSL has a lightweight utility VM that starts, stops and manages resources automatically.
• If you have no open file handles to Windows processes, the WSL VM will automatically be shut down. This means if you are using it as a web server, SSH into it to run your server and then exit, the VM could shut down because it is detecting that users are finished using it and will clean up its resources.
• WSL users have full access to their Linux instances. The lifetime of the VM, the registered WSL distributions, etc., are all accessible by the user and can be modified by the user.
• WSL automatically gives file access to Windows files.
• Windows paths are appended to your path by default, which could cause unexpected behavior for certain Linux applications compared to a traditional Linux environment.
• WSL can run Windows executables from Linux, which could also lead to a different environment than a traditional Linux VM.
• The Linux kernel used by WSL is updated automatically.
• GPU access in WSL happens through a /dev/dxg device, which routes GPU calls out to the Windows GPU. This setup is different than a traditional Linux set up.
• There are other smaller differences compared to bare metal Linux and more differences are expected to arise in the future as the inner loop development workflow is prioritized.

There are a few ways you can accomplish this task:

• The easiest way is to use the wsl --export --vhd command to export your WSL distribution to a VHD file. You can then copy this file to another machine, and import it using wsl --import --vhd. See the import and export commands in the WSL basic commands doc for more information.
• The implementation above requires a lot of disk space. If you don't have a lot of disk space you can use Linux techniques to move your files over:
  • Use tar -czf <tarballName> <directory> to create a tarball of your files. You can then copy these specific files over to your new machine and run tar -xzf <tarballName> to extract them.
  • You can also export a list of installed packages via apt with a command like so: dpkg --get-selections | grep -v deinstall | awk '{print $1}' > package_list.txt and then reinstall those same packages on another machine with a command like sudo apt install -y $(cat package_list.txt) after transferring the file over.

You can do this using PowerShell. Below are the necessary commands and explanations for each step. Please open a PowerShell window and adjust the values in between the < tags to fit your specific use case:

# Create a folder where you would like to store your distro
New-Item -ItemType Directory -Path <Install location, e.g: D:\WSLDistros\Ubuntu>

# Export your distro to that folder as a VHD
wsl --export --vhd <Distroname, e.g: Ubuntu> <Install Location with filename, e.g: D:\WSLDistros\Ubuntu\ext4.vhdx> 

# Unregister your old distro
# Please note this will erase your existing distro's file contents, please ensure the backup file you created in the 2nd step is present at the location and that the export operation completed successfully.
# Please exercise caution when using this command, as it is destructive and could cause data loss.
wsl --unregister <Distroname>

# Import your VHD backup

wsl --import-in-place <Distroname> <Install Location with filename>

# Set your default user account

You can set up your default user account by [setting a wsl.conf value of user.default=<name>](/windows/wsl/wsl-config#user-settings)

Yes. WSL 2 is available on all Desktop SKUs where WSL is available, including Windows 10 Home and Windows 11 Home.

Specifically, WSL2 requires two features to be enabled:

1. "Virtual Machine Platform" (a subset of Hyper-V)
2. "Windows Subsystem for Linux"

The newest version of WSL uses a subset of Hyper-V architecture to enable its virtualization. This subset is provided as an optional component named "Virtual Machine Platform," available on all Desktop SKUs.

We currently have no plans to deprecate WSL 1. You can run WSL 1 and WSL 2 distros side by side, and can upgrade and downgrade any distro at any time. Adding WSL 2 as a new architecture presents a better platform for the WSL team to deliver features that make WSL an amazing way to run a Linux environment in Windows.

Some 3rd party applications cannot work when Hyper-V is in use, which means they will not be able to run when WSL 2 is enabled, such as VMware and VirtualBox. However, recently both VirtualBox and VMware have released versions that support Hyper-V and WSL2. Learn more about VirtualBox's changes here and VMware's changes here. For troubleshooting issues, take a look at the VirtualBox issue discussions in the WSL repo on GitHub. StackOverflow also offers a helpful tip: How to get VirtualBox 6.0 and WSL working at the same time.

We are consistently working on solutions to support third-party integration of Hyper-V. For example, we expose a set of APIs called Hypervisor Platform that third-party virtualization providers can use to make their software compatible with Hyper-V. This lets applications use the Hyper-V architecture for their emulation such as the Google Android Emulator, and VirtualBox 6 and above which are both now compatible with Hyper-V.

See the WSL issues repo for more background and discussion on WSL 2 issues with VirtualBox 6.1.

*If you're looking for a Windows virtual machine, VMWare, Hyper-V, VirtualBox, and Parallels VM downloads are available on the Windows Dev Center.

We have released support for accessing the GPU inside of WSL 2 distributions! This means you can now use WSL for machine learning, artificial intelligence, and data science scenarios more easily when big data sets are involved. Check out the get started with GPU support tutorial. As of right now WSL 2 does not include serial support, or USB device support. We are investigating the best way to add these features. However, USB support is now available through the USBIPD-WIN project. See Connect USB devices for steps to set up USB device support.

Yes, in general networking applications will work better and be faster with WSL 2 since it offers full system call compatibility. However, the WSL 2 architecture uses virtualized networking components, which means that WSL 2 will behave similarly to a virtual machine -- WSL 2 distributions will have a different IP address than the host machine (Windows OS). For more information, see Accessing network applications with WSL.

Yes! You need to make sure that the virtual machine has nested virtualization enabled. This can be enabled in your parent Hyper-V host by running the following command in a PowerShell window with Administrator privileges:

Set-VMProcessor -VMName <VMName> -ExposeVirtualizationExtensions $true

Make sure to replace '<VMName>' with the name of your virtual machine.

WSL 2 supports the same wsl.conf file that WSL 1 uses. This means that any configuration options that you had set in a WSL 1 distro, such as automounting Windows drives, enabling or disabling interop, changing the directory where Windows drives will be mounted, etc. will all work inside of WSL 2. You can learn more about the configuration options in WSL in the Distribution Management page. Learn more about support for mounting drives, disks, devices, or virtual hard disks (VHDs) in the Mount a Linux disk in WSL 2 article.

The WSL product repo issues enables you to:

• Search existing issues to see if there are any associated with a problem that you are having. Note that in the search bar, you can remove "is:open" to include issues that have already been resolved in your search. Please consider commenting or giving a thumbs up to any open issues that you would like to express your interest in moving forward as a priority.
• File a new issue. If you have found a problem with WSL and there does not appear to be an existing issue, you can select the green New issue button and then choose WSL - Bug Report. You will need to include a title for the issue, your Windows build number (run cmd.exe /c ver to see your current build #), whether you're running WSL 1 or 2, your current Linux Kernel version # (run wsl.exe --status or cat /proc/version), the version # of your distribution (run lsb_release -r), any other software versions involved, the repro steps, expected behavior, actual behavior, and diagnostic logs if available and appropriate. For more info, see contributing to WSL.
• File a feature request by selecting the green New issue button and then select Feature request. You will need to address a few questions describing your request.

You can also:

• File a documentation issue using the WSL docs repo. To contribute to the WSL docs, see the Microsoft Docs contributor guide.
• File a Windows Terminal issue using the the Windows Terminal product repo if your problem is related more to the Windows Terminal, Windows Console, or the command-line UI.

If you'd like to stay up to date with the latest WSL news you can do so with:

• Our command-line team blog
• Twitter. Please follow @craigaloewen on Twitter to learn of news, updates, etc.

This error is caused by a group policy blocking WSL. To resolve, first run the command wsl --update to update to the latest Store version. If that doesn't resolve the issue, contact your administrator. Learn more about the difference between the inbox WSL and Store version of WSL: WSL in the Microsoft Store.