What is Windows Subsystem for Linux (WSL)?
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.
Who is WSL for?
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 (
awk, etc.) and Linux-first frameworks (Ruby, Python, etc.) but also enjoys using Windows productivity tools
What can I do with WSL?
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
Could you describe a typical development workflow that incorporates WSL?
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 (ie 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.
What is Bash?
Bash is a popular text-based shell and command-language. It is the default shell included within Ubuntu and other Linux distros, and in macOS. Users type commands into a shell to execute scripts and/or run commands and tools to accomplish many tasks.
How does this work?
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.
Why would I use WSL rather than Linux in a VM?
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.
Why would I use, for example, Ruby on Linux instead of on Windows?
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.
What does this mean for PowerShell?
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
What processors does WSL support?
WSL supports x64 and Arm CPUs.
How do I access my C: drive?
Mount points for hard drives on the local machine are automatically created and provide easy access to the Windows file system.
Example usage would be
cd /mnt/c to access c:\
How do I set up Git Credential Manager? (How do I use my Windows Git permissions in WSL?)
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.
How do I use a Windows file with a Linux app?
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
Learn more in Working across Windows and Linux file systems article.
Are files in the Linux drive different from the mounted Windows drive?
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
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
How do I uninstall a WSL Distribution?
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.
How do I run an OpenSSH server?
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 (ie 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.
How do I change the display language of WSL?
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 to locale to en-US:
sudo update-locale LANG=en_US.UTF8
Why do I not have internet access from WSL?
Some users have reported issues with specific firewall applications blocking internet access in WSL. The firewalls reported are:
- Symantec Endpoint Protection
In some cases turning off the firewall allows for access. In some cases simply having the firewall installed looks to block access.
How do I access a port from WSL in Windows?
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.
How can I back up my WSL distributions, or move them from one drive to another?
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.
Please note that traditional backup services that backup files in your AppData folders (like Windows Backup) will not corrupt your Linux files.
Does WSL 2 use Hyper-V? Will it be available on Windows 10 Home and Windows 11 Home?
WSL 2 is available on all Desktop SKUs where WSL is available, including Windows 10 Home and Windows 11 Home.
The newest version of WSL uses Hyper-V architecture to enable its virtualization. This architecture will be available in the 'Virtual Machine Platform' optional component. This optional component will be available on all SKUs. You can expect to see more details about this experience soon as we get closer to the WSL 2 release.
What will happen to WSL 1? Will it be abandoned?
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.
Will I be able to run WSL 2 and other 3rd party virtualization tools such as VMware, or VirtualBox?
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.
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.
Can I access the GPU in WSL 2? Are there plans to increase hardware support?
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.
Can WSL 2 use networking applications?
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.
Can I run WSL 2 in a virtual machine?
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.
Can I use wsl.conf in WSL 2?
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.
Where can I provide feedback?
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 verto see your current build #), whether you're running WSL 1 or 2, your current Linux Kernel version # (run
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: