WSL is the “Linux aspect” of Windows. You can execute Linux commands in Windows on your Windows files. You can pipe the output of a Windows command to a Linux program, or pipe Linux output to Windows. In the following example, the Windows winget.exe program generates a list of the current versions (and available update versions) of programs installed in the Windows operating system and the command line pipes this list to the Linux grep command which filters out the lines that contain the word “Git”
C:\Users\gilbert>winget list|wsl grep Git Git Git.Git 2.48.1 winget GitHub Desktop GitHub.GitHubDesktop 3.4.17 winget
WSL creates a very special Linux Virtual Machine running the Microsoft version of the Linux Kernel. Unlike other VMs, the Windows system is tightly connected to this Linux VM. Windows programs can directly access the Linux files, Linux has access to the Windows disks, Linux and Windows programs can share the same network adapters, and you can combine Linux and Windows programs on the same command line.
If you want the full Linux Gnome Desktop experience, create a normal Linux VM with Hyper-V. WSL is command line only, but you can install individual Linux GUI programs into WSL and when you run them an application window pops up on the Windows desktop:
The Microsoft Linux Kernel runs a special non-Docker container system. You can install one or more Linux “distributions” (Ubuntu, Debian, SUSE, etc.) each into their own container under the Kernel. Unlike Docker, this special container system lets the distributions run systemd background services and shares resources like network adapters. Each distribution has its own isolated file system, processes, and libraries.
The default and probably best adapted distribution is Ubuntu (24.04 LTS). Ubuntu has supported WSL since the earliest version, installs with systemd and snap enabled, and provides the widest library of programs that you can install and run using the apt package manager.
If you are going to run a sequence of Linux commands, then typing the command “wsl” with no arguments converts the Windows command line into a Linux bash session (like running ssh to a Linux machine on the network). Microsoft also provides a bash.exe command that does the same thing.
There is no way to translate Windows file access control to Linux file permissions. The WSL environment is, therefore, private to each Windows user. If two users are logged into the same Windows machine, each has their own personal copy of WSL Ubuntu. The user has implicit full (root) control over his own WSL system and files. Anything in WSL cannot be directly shared with another user. However, if a WSL service connects to the network as port 8080, then other users on the same machine can connect to localhost:8080 and access the service over what appears to be “the network”.
On Windows, the Linux file system in your Ubuntu distribution is referenced by the Windows UNC name of \\wsl$\ubuntu.
C:\Users\gilbert>dir \\wsl$\Ubuntu\ Directory of \\wsl$\Ubuntu 03/31/2024 04:00 AM <DIR> sbin.usr-is-merged 02/11/2025 07:59 PM 2,424,984 init 09/27/2024 03:13 PM <DIR> srv 11/23/2024 08:12 PM <DIR> mnt 03/07/2025 11:42 AM <DIR> proc 03/07/2025 11:42 AM <DIR> dev
In Linux, your Windows disk letters appear as subdirectories of /mnt
ls -ltr /mnt total 0 drwxrwxrwx 1 gilbert gilbert 4096 Mar 7 11:16 d drwxrwxrwx 1 gilbert gilbert 4096 Mar 7 11:16 c drwxrwxrwx 1 gilbert gilbert 4096 Mar 7 11:16 e drwxrwxrwt 2 root root 60 Mar 7 11:48 wsl drwxrwxrwt 7 root root 300 Mar 7 11:48 wslg
While /home/username is your Linux home directory, when you run a Linux program from Windows then the program starts in the same current directory that Windows had, expressed through the mapping:
C:\Users\gilbert>wsl gilbert@MWPFxxxxx:/mnt/c/Users/gilbert$
When you go from Windows to Linux, your Windows Environment variables are merged with Linux environment variables.
In Linux, if you type a command that turns out to be a *.exe program, the Microsoft Linux Kernel handles the transition from Linux back to Windows. At this time there is no way for Windows to automatically recognize a Linux program, so you have to run “wsl <programname>”. However, you can create a programname.bat file somewhere in your Windows path. For example, grep.bat could contain:
wsl grep %*
and then when you run the “grep” command in Windows it will run the Linux program with all the same arguments.
Installation
You can install WSL and the distribution from the Windows Store in Windows 11. However, there is no Store in Windows Server 2025, so you might as well get used to the command line.
If WSL is not installed, run an elevated (Run as administrator) command prompt and enter
wsl --install
This installs the minimal Hyper-V feature, then downloads and installs the Microsoft Linux Kernel, and finally downloads and installs the default Ubuntu distribution. This requires a reboot to complete the installation. When you run wsl for the first time, the Ubuntu system will go through a first time initialization asking you to enter the userid and password that will administer the system.
Some WSL Implementation Internals
Bell Labs created Unix when computers were big expensive machines shared by users. One people switched to using networks of smaller computers, they started work on a successor to Unix with a codname of “Plan 9”. The idea was to make a network of PCs look like a single system with a lot of users. Files on different computers would appear to be one big file system, and programs and servers running on different machines would look like they were all running in one operating system. To make this work, they developed a very powerful network-based disk sharing and program to program communication protocol named “9P”.
Microsoft adopted 9P as a way to combine the Windows OS (disks, files, programs) with a Linux OS so that the combination of two systems looked to the user like a single tightly integrated system. However, the Microsoft adaptation of 9P runs between a logged in Windows user and the WSL Linux VM started by that logged in user.
While Windows and Linux assume that everything is private by default and a user has to explicitly share disks or directories with the network, the 9P model is that everything is shared by default and something is private by setting permissions. This aligns with the view that while you are logged into Windows and running WSL, your Windows programs have full access to everything on your personal copy of a WSL distribution, and WSL programs you run have access to anything on Windows that you (the currently logged in user under which WSL is running) have access to.
WSL originally ran in single user mode (like a Docker container). Then Microsoft added support for systemd by adding an option in the /etc/wsl.conf file in the WSL distribution file system. Ubuntu defaulted to enabling systemd after 23.10.
WSL has some complicated rules for networking that require their own section.
The Distros
Microsoft provides the Hyper-V feature and the Linux Kernel.
Some of the groups and companies that create real Linux distributions also configure and package the tar files that contain a configuration of their system suitable for use in WSL. There are also GitHub communities that build tar files you can download and import yourself.
wsl --install --online
This command will list the names of WSL Distributions that have been contributed and accepted into a Microsoft library. Any of them will be downloaded and installed with the command
wsl --install <distroname>
You can have more than one distribution installed on your system. Each distribution runs under the Microsoft Linux Kernel in one of the special non-Docker containers. The container separates the file system and memory of each running distro, but they share a single kernel and see side effects of the activities of programs in other containers. In particular, after any program in any container binds to a port number on any network adapter, programs in other distro containers attempting to bind to the same port number will get the error return that the port is already in use by another program.
The default distribution is “Ubuntu” which at the time of writing is version 24.04. Canonical has been the most enthusiastic supporter of WSL and tends to be the first to support new features added by Microsoft. In particular, Canonical maintains libraries of installable programs that reflect WSL improvements such as support for graphic applications and the availability of systemd.
The “wsl --install <distroname>” only works with distronames supplied by Microsoft, and you can only have one installed configuration for each name. Canonical provides two names for what turns out to be identical distributions: “Ubuntu” and “Ubuntu-24.04” install two separate copies of the same system. Once installed, the running distros have separate file systems and therefore separate programs and libraries.
If you need a third instance of Ubuntu, or a second instance of one of the other available distros, or you want to backup a distribution after you have carefully configured one and installed just the right packages, or you want to copy this carefully crafted distribution to another computer, then you can generate your own tar file of the distribution with the “wsl --export”. You can use this tar file to create a second copy of the distribution with a different name on the same computer, or you can copy it to another computer and use it to create a copy of the same distribution+configuration+packages+program using the “wsl --import” command.
If you are inclined to create a distro from a Beta version of Ubuntu, they keep compressed tar files in a public Web site called https://cloud-images.ubuntu.com/releases/. Remember to unzip the file because “wsl --import” takes a tar and not a tar.gz file.
One distro is designated the Default. It is the distro you run when you type the “wsl” command without a distro name.
WSL Networking
This is a subject that is constantly being changed by Microsoft, but there are a few basic ideas that remain constant.
Concept: There is one “localhost” shared by Windows and WSL
Actually, localhost (address 127.0.0.1) is a device driver in both the Windows and Linux Kernel. It is always a virtual network adapter with no real network and no physical device. It allows two programs on the same computer to talk to each other as if they were talking through a network.
The Localhost device drivers in Windows and Microsoft Linux have been modified to know about each other and the Hyper-V system that connects them. They coordinate their actions to behave as if they were a single entity. When programs bind to port numbers, the two drivers synchronize this operation so that only one program on either system owns the port. When data is transferred between clients and servers, Hyper-V is called to move the data when one program is on Windows and the other is in WSL.
It was previously noted that multiple distributions running in containers on the WSL Kernel share the Linux localhost device. As a result, localhost can be used to communicate between two programs whether they are running in the same system, one is in Windows and one is in a WSL distro, or each is in a different Linux distro.
At the time this is being written, there is experimental support to extend the behavior of Localhost to all the other real network adapters. This is called “mirrored” networking. When enabled, the Linux Kernel gets a virtual network adapter for every physical network adapter on the Windows host system. The device drivers in Windows and Linux synchronize port assignment, and Hyper-V moves data between the Linux virtual device and the Windows physical device as needed. Again, the distro containers share the same Linux device in the kernel.
There may be some rough edges trying to make this work, which is why the support is still labelled experimental.
Without network mirroring, WSL creates a shared Localhost device, and then one virtual network adapter in the Linux Kernel that is connected to a gateway service in the Windows host. This is separate from the Hyper-V Default network because it is not connected to Hyper-V VMs, but it provides essentially the same general Internet access service.