Installing Windows Subsystem for Linux (WSL) on Windows 11

3.5K

Windows Subsystem for Linux or WSL lets you run Linux distributions, apps, and command-line tools directly on Windows without setting up a traditional VM/dual-boot config. WSL 2 uses a real Linux kernel running in a lightweight virtualized environment, while WSL 1 uses a system-call translation layer.

Our guide focuses on installing and configuring WSL 2 on Windows 11, which is the recommended architecture for running modern Linux distributions on Windows. WSL is also available on supported Windows 10 builds (however, don’t forget that Windows 10 reached end of support on October 14, 2025).

Note that in 2026, the WSL package has moved into the 3.x release line, while Linux distributions continue to run using the WSL 2 architecture. As a result, references to WSL 2 in our guide describe the Linux execution architecture, while WSL 3.x refers to the installed WSL runtime/package version.

WSL is open source. Since 2025, WSL has been developed as an open-source project. Microsoft publishes the WSL source code and development activity publicly, making the project more transparent and allowing the community to review, contribute to, and track changes to the WSL components. For admins this also provides an additional source for tracking new WSL features, fixes, and changes alongside the official Microsoft documentation.

WSL1 vs WSL2: What’s the Difference?

Note that you should use WSL 2 unless a specific app requires WSL 1 compatibility for new Windows 11 deployments. WSL 1 remains available for legacy cases but is no longer the recommended architecture for new deployments.

Prerequisites for WSL2 installation on Windows 11

• Computer with hardware virtualization support enabled in BIOS. Check if hardware virtualization is enabled in Task Manager on the Performance > CPU tab. If not, enable Virtualization Technology, VTx, Secure Virtual Machine (SVM), or similar options in the BIOS settings.
  

• Windows 11 is the primary client platform covered by our guide. WSL 2 is available on supported Windows 11 editions, including Home and Pro. Hardware virtualization must be enabled in UEFI/BIOS. In case Windows 11 is running inside a VM, nested virtualization must also be enabled.

Common WSL Installation Errors

In case WSL 2 fails to start/installation reports a virtualization-related error, you should check the following:

• Virtual Machine Platform is disabled. You need to ensure that the Virtual Machine Platform optional Windows feature is enabled.
• The Windows hypervisor is disabled. You can check the boot config with the following command:

  bcdedit /enum "{current}" | findstr /i "hypervisorlaunchtype"

  The expected value is:

  hypervisorlaunchtype Auto

• Nested virtualization is not enabled. In case Windows 11 is running inside a VM, the hypervisor hosting the VM must expose nested virtualization to the guest.
• Windows build or WSL components are outdated. You can check the installed WSL version and status with:

  wsl --status
  wsl --version

• Security or virtualization policies interfere with WSL. In managed environments, Hyper-V, virtualization-based security, endpoint protection, or organizational policies may restrict WSL functionality.

Installation of WSL 2 on Windows 11

Microsoft has made the installation of WSL 2 on Windows 11 incredibly easy. Just open an elevated Terminal (or PowerShell) console and run:

wsl --install

This command automatically performs the following steps:

1. Enables the optional WSL and Virtual Machine Platform components.
2. Downloads and installs (updates) the latest version of the WSL kernel.
3. Sets WSL2 as the default environment.
4. Downloads and installs the default Linux distribution from the Microsoft Store.

Restart the computer once the command is finished. Note that a restart is required only when the WSL components are being installed for the first time. Subsequent distro installations do not require a reboot.

After the reboot, you will see an Ubuntu Linux terminal asking you to set the username and password.

Download and install the WSL manually

If Microsoft Store access is unavailable/restricted by organizational policy, or if you need to deploy WSL in an offline/controlled environment, you can install WSL manually using the standalone WSL package:

1. Install the Virtual Machine Platform and Windows Subsystem for Linux features from the Turn Windows features on or off GUI (optionalfeatures.exe). Or using the commands:
   

   dism.exe /online /enable-feature /featurename:Microsoft-Windows-Subsystem-Linux /all /norestart
   
   dism.exe /online /enable-feature /featurename:VirtualMachinePlatform /all /norestart

   Don’t forget to restart Windows after enabling the optional feature.
   
2. Download and install the latest WSL MSI package from the official WSL releases page. This is the recommended package for offline or Microsoft Store-independent WSL installation.
   

   

3. Set WSL 2 as default for Linux distributions:
   

   wsl --set-default-version 2

   The command above changes the default WSL architecture used when new distributions are installed. Keep in mind that it does not convert existing WSL 1 distributions.

4. Now verify WSL Installation. The following commands verify the installed WSL version, Linux kernel version, and default subsystem config:

   wsl --status
   wsl --version

5. Download your preferred Linux distro for WSL. To see the distributions currently available for installation, run the command:
   

   wsl --list --online

   
6. Install a distribution by specifying its name:
   

   wsl --install -d Ubuntu

For offline/custom WSL deployments, you can import a Linux distribution from a TAR file. The first argument after wsl –import is the name of the new WSL distribution, so use a unique name if another distribution with the same name is already installed.

Here is an example:

wsl --import Ubuntu-Imported D:\WSL\Ubuntu-Imported .\ubuntu.tar --version 2

After the import, the distribution starts as the root user by default. In case you want to use a regular Linux user, you need to create/use an existing user inside the imported distribution and config it as the default user according to the distribution’s config mechanism.

You can verify the imported distribution and its default state with:

wsl --list --verbose
wsl -d Ubuntu-Imported

Then check the current Linux user:

whoami

Using WSL

List installed Linux distros in WSL

wsl --list

Set default distro for the WSL environment

wsl --set-default <DistributionName>

Convert an Existing WSL 1 Distribution to WSL 2

Keep in mind that WSL 1 is a legacy architecture. For existing distributions that still use WSL 1, you can convert them to WSL 2 without reinstalling the distribution. First, you need to check the current WSL architecture:

wsl --list --verbose

Now convert the distribution:

wsl --set-version <DistributionName> 2

Here is an example:

wsl --set-version Ubuntu 2

Note that converting a large distribution can take some time. For important systems, you need to create a backup with wsl –export before migration.

Run the default Linux distro

wsl

Run a specific distro

wsl -d Debian

Update packages inside an Ubuntu/Debian distribution

sudo apt update && sudo apt upgrade

Update WSL to the Latest Version

WSL is updated independently of the Windows OS. In order to check for and install the latest available WSL update, run the command:

wsl --update

This command updates the WSL package and its components. You can verify the installed WSL version with the following:

wsl --version

In case WSL distributions are currently running, you can shut them down separately with:

wsl --shutdown

The wsl –shutdown command terminates all running WSL distributions and the WSL 2 VM. It is not part of the update command. You should use it when you need to restart the WSL environment, for example after changing WSL config settings or when you want to ensure that newly applied WSL settings are loaded.

Host computer resources available to WSL2 by default

How to limit host resource usage

Edit your WSL environment configuration file to limit host resource usage:

1. Terminate the VmmemWSL process:
   

   wsl --shutdown

2. Create or edit the .wslconfig file in your Windows user profile:
   

   notepad "$env:USERPROFILE/.wslconfig"

   The .wslconfig file is stored in %UserProfile%/.wslconfig and controls WSL 2 VM settings for the current Windows user.
3. For example, you can limit the amount of memory and the number of logical processors available to WSL 2:
   

   [wsl2]
   memory=4GB
   processors=4

   These values are examples only. You need to choose the limits based on the host’s available CPU and memory resources and the workload running in WSL. Note that you should avoid allocating so many resources to WSL that Windows and other apps become resource-constrained.
   
4. After saving the file, restart the WSL 2 environment:
   

   wsl --shutdown

Now you can run any native Linux command from within the Windows CLI:

wsl <linux-command>

For example, list all files in a Windows folder:

wsl ls -la

Keep in mind that Linux filesystem operations are significantly faster inside the native Linux filesystem than inside mounted Windows drives (/mnt/c). For best performance, you should store development projects inside the WSL Linux filesystem (instead of the Windows filesystem).

Using Docker with WSL2

WSL2 is widely used as the backend for Docker Desktop on Windows 11. Docker uses the WSL2 virtualization layer to run Linux containers with improved performance and compatibility. Note that most modern containerized development environments on Windows rely on WSL2 integration.

WSL in Enterprise Environments

Keep in mind that in enterprise environments, WSL installation may be restricted by:

• Group Policy settings;
• Microsoft Intune policies;
• Hyper-V restrictions;
• virtualization-based security (VBS);
• corporate endpoint protection software.

In some organizations, WSL is disabled completely due to security/compliance requirements.

Remote Access to WSL

By default, WSL 2 uses NAT networking. Windows can access services running in WSL through localhost forwarding, but inbound connections from other network devices are not enabled by default.

On supported Windows 11 versions, WSL 2 also supports mirrored networking mode. With mirrored networking enabled, WSL can use the host’s network interfaces more directly, including improved support for inbound LAN connections. Access to WSL services from the network may still require appropriate Hyper-V firewall rules.

[wsl2]
networkingMode=mirrored

After changing networking settings, restart WSL:

wsl --shutdown

Accessing WSL files from Windows

In order to access the files of your WSL distribution from Windows, use the following UNC path:

\\wsl.localhost\Ubuntu\

Wrapping up

WSL2 provides one of the easiest ways to run native Linux workloads on Windows 11. This allows you to run Linux workloads without configuring a separate VM or dual-boot environment. For most cases, the simplest installation method is to use the command:

wsl --install

In case you are an advanced user or enterprise admin, you may additionally customize resource usage, networking, Linux distributions, and integration with development tools (such as Docker).