Skip to content
Français
Account: not signed in, sync available My learning
Select theme
Français
Lire en français

Install WSL2 on Windows 11 (or Windows 10) for a local Linux

By updated

Improve this page

WSL2 (Windows Subsystem for Linux 2) runs Linux directly inside Windows, without dual-boot (two systems installed side by side, chosen at startup) and without a heavy virtual machine to manage. You keep Windows as it is, and you get a Linux terminal with bash, Python and every command-line tool that only exists on Linux. This page takes a Windows PC to an open Ubuntu window, with your user created and the system up to date. On Windows 11, a single command is enough; Windows 10 is still supported by WSL, with the limits pointed out in the prerequisites. For a full Linux in its own virtual machine, see Install Linux in a virtual machine instead.

What you will learn

This guide walks you through the installation and configuration of WSL2, from the hardware prerequisites to graphical applications:

SkillWhat you will be able to do
Check the prerequisitesConfirm that your PC supports WSL2
Turn on virtualisationConfigure the BIOS if needed
Install WSL2One command to set everything up
Open UbuntuCreate your Linux user and update the system
Choose a distributionUbuntu by default, or another one from the Microsoft catalogue
Manage your distributionsList, stop, back up and restore
Run graphical appsRun Linux applications with an interface
Offline installationInstall WSL without an Internet connection

Understanding WSL2

Before typing a single command, you need to know which of the two versions of WSL you are using. The choice is made distribution by distribution, and it changes both performance and compatibility. This section compares the two architectures, then explains why the recommendation almost always leans the same way.

WSL1 vs WSL2: what is the difference?

WSL1 and WSL2 coexist and are chosen distribution by distribution. WSL1 translates Linux system calls into Windows calls. WSL2 embeds a real Linux kernel in a lightweight virtual machine managed by Hyper-V, the Windows hypervisor (the software that runs virtual machines).

AspectWSL1WSL2
ArchitectureTranslation layerReal Linux kernel
Read/write (I/O) of Linux filesAverageHigh
Read/write (I/O) of Windows filesHighAverage
CompatibilityPartialNear-total
RAM usedMinimalDynamic (up to 50% of the RAM by default)

The two performance rows read as mirror images. WSL1's translation reads Windows files fast but Linux files slowly. WSL2's virtual machine does the opposite, because its Linux files live in a virtual disk and access to C: goes through a network protocol.

Use WSL2 unless you work mostly on files stored on the Windows side: in that case, WSL1 can remain faster for file access.

WSL2 embeds a Linux kernel built and distributed by Microsoft. Linux applications find there what they expect, hence the near-total compatibility. Tools that rely on the kernel benefit from it: Docker Desktop, for example, uses the WSL 2 engine to run Linux containers on Windows.

Prerequisites

Two conditions decide everything else: a recent enough Windows version, and hardware virtualisation turned on in the firmware. Check both before starting the installation.

Required Windows version

WSL2 works on Windows 11, or on Windows 10 version 2004 or later. The number that matters is not "Windows 10" but the build number: a machine still on a build older than 19041 refuses the wsl --install command, even though it does show Windows 10. To read it, press Win+R, type winver and confirm (the command also works in a terminal):

Terminal window
winver

You must see at least:

  • Windows 11: every supported version
  • Windows 10: version 2004 (build 19041 or later)

Windows 10 has no longer been supported by Microsoft since 14 October 2025: only the Extended Security Updates (ESU) programme still provides fixes, until 12 October 2027 for individuals (pages read on 2026-11-13). WSL itself still lists Windows 10 among the supported versions. For a new machine, prefer Windows 11.

Turn on virtualisation (BIOS/UEFI)

WSL2 relies on Hyper-V, which requires the processor's hardware virtualisation (Intel VT-x or AMD-V). On most recent PCs it is already turned on: check before touching the BIOS. Open Task Manager (Ctrl+Shift+Esc), Performance tab, then CPU: the Virtualization line must show "Enabled".

If it shows "Disabled", or if the installation fails with a virtualisation error, turn it on in the BIOS/UEFI. This is the settings menu of the motherboard, which opens at startup before Windows.

  1. Restart your PC and enter the BIOS/UEFI

    The key depends on the manufacturer (it is shown at startup); the table in the next step gives the most common ones.

  2. Find the virtualisation setting

    Its name and location vary by manufacturer:

    ManufacturerBIOS keyLocationSetting name
    ASUSF2 / DelAdvanced → CPU ConfigurationIntel VT-x / SVM Mode
    DellF2Virtualization SupportEnable Virtualization
    HPF10 / EscSystem Configuration → Device ConfigurationVirtualization Technology
    LenovoF1 / F2Security → VirtualizationIntel VT-x / AMD-V
    MSIDelOC → CPU FeaturesSVM Mode / Intel VT-x
    AcerF2AdvancedIntel VT / AMD SVM
    GigabyteDelM.I.T → Advanced CPU SettingsSVM / VT-x

    This table sums up the most common paths. The setting must be on Enabled.

  3. Save and restart

    Usually F10 → Save & Exit.

Installing WSL2

Two paths lead to the same result, and the choice depends on your network access. On a connected machine, wsl --install chains on its own the feature activation, the kernel download and the installation of a distribution. Behind a filtering proxy or on an isolated machine, the same sequence is redone by hand, file by file. Start with the standard method: the offline method only makes sense if this one fails at download time.

Standard method (with Internet)

A single PowerShell command run as administrator turns on the Windows features, downloads the kernel and installs a distribution. Five steps take you from a blank PC to an open Ubuntu window. The point not to miss is the restart between step 2 and step 4: Microsoft asks you to restart the PC after wsl --install, and the installation of Ubuntu continues at that restart.

  1. Open PowerShell as administrator

    • Right-click Start → Windows Terminal (Admin)
    • Or: Win+X → Terminal (Admin)
  2. Start the installation

    Terminal window
    wsl --install

    This command:

    • Turns on the required Windows features
    • Downloads the WSL2 Linux kernel
    • Installs Ubuntu as the default distribution
  3. Restart your PC

    Terminal window
    Restart-Computer
  4. Set up Ubuntu on first launch

    After the restart, Ubuntu starts by itself and finishes its installation, which takes a few minutes. If no window opens, type Ubuntu in the Start menu and click the application. Ubuntu asks you to create your Linux user, then a password. When you type the password, nothing is displayed, not even dots: this is normal. Type it anyway, then confirm it. Remember it, because Linux will ask for it again.

    Enter new UNIX username: your_name
    New password:
    Retype new password:
  5. Check the prompt and update Ubuntu

    When the installation is finished, the window shows a prompt like your_name@PC:~$: your user, the name of your PC, then the current directory. You are in a Linux terminal. Update the packages before going on. The sudo command asks for your password, again without displaying anything:

    Terminal window
    sudo apt update && sudo apt upgrade -y

    To reopen Ubuntu after closing it, type Ubuntu in the Start menu, or wsl in PowerShell. The lesson Open a terminal and understand the prompt explains how to read this prompt.

To check that Ubuntu runs on WSL2, open PowerShell and run wsl --list --verbose: the VERSION column must show 2.

Ubuntu is only the default distribution, not a requirement. The -d option installs another one, and you can install several side by side on the same machine:

Terminal window
wsl --install -d Debian

The wsl --list --online command shows the catalogue of names accepted by -d. It is the only authoritative list: a name found elsewhere fails if the image is not published for your WSL version. If the download stays stuck at 0.0%, Microsoft advises wsl --install --web-download -d <Distribution>.

Offline method (without Internet)

In a disconnected environment or behind a filtering proxy, wsl --install fails when downloading the kernel. The procedure below redoes by hand what the command automates: turn on two Windows features, install the kernel package, then provide the distribution as a file. Microsoft documents it under the title Manual installation steps for older versions of WSL. Plan a connected machine to fetch the two files, and a means of transfer (USB stick, internal share).

  1. Turn on the required Windows features

    In an administrator PowerShell:

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

    Terminal window
    Restart-Computer
  3. Download the kernel update package

    On a connected PC, download the official package for your architecture, wsl_update_x64.msi or wsl_update_arm64.msi, from the Manual installation steps page on Microsoft Learn. Transfer the .msi file and install it.

  4. Make WSL2 the default version

    Terminal window
    wsl --set-default-version 2
  5. Install a distribution manually

    A distribution's Microsoft Store page does not let you download its package. Take the direct link published in the Downloading distributions section of the same page, for example for Ubuntu 22.04 and Debian:

    Terminal window
    Invoke-WebRequest -Uri https://aka.ms/wslubuntu2204 -OutFile Ubuntu.appx -UseBasicParsing
    Invoke-WebRequest -Uri https://aka.ms/wsl-debian-gnulinux -OutFile Debian.appx -UseBasicParsing

    On the target machine, install the package then start the distribution:

    Terminal window
    Add-AppxPackage .\Ubuntu.appx

    Renaming the .appx to .zip to extract it is only the Windows Server variant, where Add-AppxPackage is not available.

Essential commands

Here are the PowerShell commands you will need day to day. They all run from a Windows terminal, not from inside WSL: they can therefore act on a stopped distribution.

Managing distributions

Once WSL is installed, you can have several Linux distributions side by side. These commands list them, start them, stop them or change the default distribution, each one by its name.

Terminal window
# List the installed distributions
wsl --list --verbose
# Start a specific distribution
wsl -d Ubuntu
# Set the default distribution
wsl --set-default Ubuntu
# Stop every distribution
wsl --shutdown
# Stop a specific distribution
wsl --terminate Ubuntu

Managing WSL versions

You can convert an existing distribution from WSL1 to WSL2 (or the other way round) without reinstalling it. It is useful if you migrated from an older version of Windows.

Terminal window
# Check the WSL version
wsl --version
# Convert a distribution WSL1 → WSL2
wsl --set-version Ubuntu 2
# Update WSL
wsl --update

Accessing files

The file systems are reachable from both sides. On the Windows side, two paths lead to the distribution: \\wsl.localhost\ and the older \\wsl$\. They point to the same place, and the distribution must be running. The table gives the first one:

FromToPath
WindowsLinux\\wsl.localhost\Ubuntu\home\user\
LinuxWindows/mnt/c/Users/YourName/

Linux graphical applications

WSL2 runs Linux graphical applications thanks to WSLg, a component that starts together with the distribution and relays the display to the Windows desktop. A Linux window appears like an ordinary Windows window, with its entry in the taskbar. There is no third-party X server to install, and no variable to export.

Microsoft Learn sets the prerequisite: Windows 11 or Windows 10 build 19044 or later, an up-to-date WSL, and the manufacturer's graphics driver (Intel, AMD or NVIDIA) installed on the Windows side.

Checking support

WSLg provides a Wayland display server and an X11 bridge in the distribution. To test it, read the DISPLAY variable: if it is empty, WSLg is not active and no window will open, whatever package is installed. One possible cause is a WSL that is too old, which wsl --update fixes.

Terminal window
# In WSL2, check that DISPLAY is set
echo $DISPLAY
# Must show something like :0

Installing a graphical application

A Linux graphical application installs like a command-line application, with the distribution's package manager. No display configuration is needed. Updating the package index first (apt update) avoids installing an outdated version, and apt install adds on its own the GTK or Qt libraries the application depends on.

Terminal window
# Update the packages
sudo apt update && sudo apt upgrade -y
# Install a graphical editor (example: GNOME Text Editor)
sudo apt install gnome-text-editor -y
# Start the application
gnome-text-editor &

The application opens in a classic Windows window, integrated into the taskbar.

Common applications

Here are a few common graphical applications to install in WSL2. They integrate with Windows: icons in the Start menu, resizable windows, copy and paste between Windows and Linux.

Terminal window
# File browser
sudo apt install nautilus -y
# Code editor (lightweight)
sudo apt install geany -y
# Advanced terminal
sudo apt install terminator -y

After installation, start each application by its name in the WSL terminal, for example nautilus &. The ampersand & gives control back to the terminal instead of blocking it while the window stays open.

The terminal is not needed afterwards: these applications appear in the Windows Start menu, among the Windows applications, and can be pinned to the taskbar like any of them. WSLg publishes these shortcuts from the .desktop files installed by the package.

Advanced configuration

Two configuration files coexist, and it is easy to mix them up. The diagram shows where each one lives: .wslconfig is a single Windows file that sets the virtual machine shared by all distributions; each distribution has its own /etc/wsl.conf, which only concerns that one.

A Windows PC holds the .wslconfig file, which sets the memory, processors and swap of the WSL2 virtual machine. This virtual machine is unique and holds two distributions, Ubuntu and Debian. Each one carries its own /etc/wsl.conf file, for systemd and mounts.Windows PC.wslconfiguser folderShared WSL2 virtual machineUbuntuDebian/etc/wsl.confsystemd, mounts/etc/wsl.confsystemd, mountsmemory, CPU, swap
Source · SVG
Esc to close, + and − to zoom, scroll to move around. 100 %

Remember the split rule: everything about the memory, processors and network of the VM is global, everything about systemd and mounts is local.

Limiting resources (.wslconfig)

By default, the WSL2 virtual machine can use up to 50% of the host's memory, plus a swap of 25% of that memory. The .wslconfig file sets a ceiling, which prevents a build in WSL from slowing down the rest of the machine. It applies to all distributions at once, unlike wsl.conf covered just after. Recent versions also offer the WSL Settings application, in the Start menu, which writes this same file.

The file is created at this location: C:\Users\YourName\.wslconfig

[wsl2]
memory=4GB
processors=2
swap=2GB
localhostForwarding=true

After a change, restart WSL:

Terminal window
wsl --shutdown

Per-distribution configuration (wsl.conf)

Where .wslconfig sets the global virtual machine on the Windows side, /etc/wsl.conf sits inside each distribution and only concerns that one. It is the file that turns on systemd, the Linux service manager. Microsoft states that many distributions, Ubuntu included, start it by default. On a distribution that does not turn it on, without this setting, systemctl returns an error and no Linux service starts at launch.

Microsoft specifies that the [boot] section is only available on Windows 11 and Windows Server 2022. Create the file with root rights:

[boot]
systemd=true
[automount]
enabled=true
root=/mnt/
options="metadata,umask=22,fmask=11"
[network]
generateResolvConf=true

This configuration:

  • Turns on systemd (Linux services)
  • Sets up the automatic mounting of Windows drives
  • Generates /etc/resolv.conf automatically

VS Code integration

VS Code works here in client-server mode: the interface stays a Windows application, but a VS Code server is installed automatically in the Linux distribution, and it is the one that runs the terminal, the extensions, the debugger and the language tools. Practical consequence: extensions must be installed on the WSL side, and an extension present on the Windows side may appear greyed out until you turn it on in the remote context.

  1. Install the Remote - WSL extension

    In VS Code, install "Remote - WSL" (or "WSL" in recent versions).

  2. Open a WSL project

    From WSL:

    Terminal window
    cd ~/my-project
    code .

    Or from VS Code: Ctrl+Shift+P → "WSL: Connect to WSL"

  3. Develop natively

    VS Code runs on the Windows side but every tool (terminal, extensions) runs in WSL.

Troubleshooting

The WSL failures covered here fall into three families: virtualisation missing or turned off, an outdated component that wsl --update brings up to date, and a distribution whose internal state is broken. The "Common errors" subsection mostly handles the first two with a lookup table. The third is fixed by the reset, which destroys data and must therefore be prepared before running it.

Common errors

The first column sums up messages whose exact wording varies with the WSL version and the Windows language: look for the keyword (virtualization, update, elevation) in what your terminal shows. The first three errors are fixed outside the distribution (BIOS, rights, WSL update). The fourth concerns the installation of Ubuntu itself. The fifth changes the configuration of the virtual machine: it needs a wsl --shutdown before the fix takes effect. The last one is a matter of network and VPN.

ErrorLikely causeSolution
"Virtualization disabled"BIOS badly configuredTurn on VT-x/AMD-V in the BIOS
"WSL 2 requires an update"Outdated kernelwsl --update
"The requested operation requires elevation"Insufficient rightsRun PowerShell as admin
No Ubuntu window after the restartThe installation of Ubuntu did not finishType Ubuntu in the Start menu; otherwise run wsl --install -d Ubuntu again
Distribution that does not startNot enough RAM on the Windows hostLower memory in .wslconfig
Network unavailableVPN interferenceTurn off the VPN or configure the firewall

Resetting a distribution

If a distribution is corrupted, the only reset goes through unregistering it, which wipes everything: export what matters first.

Terminal window
# Unregister (deletes the data!)
wsl --unregister Ubuntu
# Reinstall
wsl --install -d Ubuntu

Exporting/importing a distribution

wsl --export produces a .tar archive holding the distribution's whole file system: installed packages, personal files, configuration. It is the backup mechanism provided as standard, and it serves as much to migrate to another machine as to move a distribution to another disk when C: fills up. On import, the second argument is the destination directory of the virtual disk, not a file: give an empty folder.

Terminal window
# Back up
wsl --export Ubuntu D:\Backups\ubuntu.tar
# Restore (on another PC or after a reinstall)
wsl --import Ubuntu C:\WSL\Ubuntu D:\Backups\ubuntu.tar

Installation checklist

Use this list to confirm that your WSL2 installation is complete and working. Each item matches a step not to skip.

  • Windows 11, or Windows 10 2004+
  • Virtualisation turned on in the BIOS
  • wsl --install run successfully
  • Distribution set up (user + password)
  • Ubuntu open, your_name@PC:~$ prompt visible, packages updated
  • wsl --list --verbose shows the distribution in version 2
  • Working network access (sudo apt update succeeded in step 5)
  • .wslconfig created to limit RAM (optional)

Key points

These points sum up what to keep in mind to use WSL2 day to day, from installation to backup.

ConceptKey point
WSL2A real Linux kernel in a lightweight virtual machine, not an emulation
Installationwsl --install does everything in one command, then the PC restarts
First launchUser created, password invisible as you type it, packages updated with sudo apt update && sudo apt upgrade -y
FilesWork in your app's native file system
ResourcesLimit RAM through .wslconfig if needed
Graphical applicationsWSLg, on Windows 11 or Windows 10 build 19044+
VS CodeWSL extension to develop natively
Backupwsl --export before any risky operation

Knowledge check

Check that the essentials of this guide stuck. The questions only cover what has just been explained here.

Knowledge check

Check what you have learned with this interactive quiz

6 questions
6 min
70% to pass

How it works

  • The timer starts when you click Start
  • Multiple choice, true/false and short answer questions
  • You can move between questions
  • Detailed results are shown at the end

Starts the quiz and the timer

FAQ: frequently asked questions

These questions come up often after a first installation, and they cover points the guide handles in different places: the choice between WSL1 and WSL2, access to Windows files from Linux and the use of Docker in the distribution.