What is WSL and how to install it on Windows

WSL (Windows Subsystem for Linux) is a Windows feature that allows running a Linux environment without configuring a traditional virtual machine or resorting to dual boot.

With WSL you can use Bash, Git, Python, Node.js, and many other Linux tools without leaving Windows. Additionally, both systems are integrated with each other, allowing you to access Windows files from Linux, run Windows applications from Bash, or edit a Linux project with Visual Studio Code.

What is WSL

For a long time, working on Windows with tools designed for Linux meant installing a virtual machine, maintaining a second partition, or settling for partial solutions like Cygwin or Git Bash.

WSL provides a GNU/Linux environment within Windows where you can install a distribution like Ubuntu or Debian. It is not a command emulator: it runs Linux binaries and tools without modification and integrates them with the Windows desktop.

This is particularly useful for tasks such as:

• Web development with Node.js, Python, Ruby, or PHP.
• Automation via Bash and other Linux utilities.
• Connecting to and managing servers using ssh, scp, or rsync.
• Compiling and testing applications intended for Linux servers.
• Using Linux containers with Docker Desktop.
• Learning Linux without changing the operating system of your computer.

Differences between WSL 1 and WSL 2

There are two architectures for WSL. Both allow running Linux distributions, but WSL 2 is the default and recommended option for most cases.

WSL 1 translates Linux system calls into operations that Windows understands. This reduces resource consumption and provides fast access to files stored on Windows, but it does not implement all features of a Linux kernel.

WSL 2 runs a Linux kernel inside a lightweight virtual machine managed by Windows. You don’t have to create virtual disks, configure networks, or maintain that machine, but a virtualization layer still exists.

For general development, containers, or projects that use many Linux tools, choose WSL 2. WSL 1 remains useful in specific situations, for example, when a project must stay on the Windows file system and is constantly accessed from tools on both systems.

You can find a more detailed comparison in the official Microsoft documentation.

Requirements for installing WSL

The modern method we will look at requires Windows 11 or Windows 10 version 2004 and build 19041 or later. You can check your installed version by pressing Win + R, typing winver, and pressing Enter.

You also need an account with administrator permissions, an internet connection, and enough space for WSL, the distribution, and the tools you plan to install. To use WSL 2, virtualization must be enabled in the computer’s BIOS or UEFI.

How to install WSL

The current installation is done with a single command. Open PowerShell or Windows Terminal as administrator and run:

wsl --install

This command enables the necessary components, installs WSL 2, and downloads Ubuntu as the default distribution. When it finishes, restart Windows if the installer prompts you.

Choosing another distribution

Ubuntu is a reasonable choice to start with, but it is not the only one. To see the available distributions, run:

wsl --list --online

Use exactly the name that appears in the NAME column. For example, to install Debian:

wsl --install -d Debian

You can install multiple distributions at the same time and maintain separate environments for different projects. You can also install them from the Microsoft Store, although the command line is usually faster and makes it clearer which distribution you are adding.

If you run wsl --install and only see the command help, it usually means WSL is already installed. In that case, list the available distributions and install one by specifying its name with -d.

First Linux configuration

The first time you open a distribution, WSL will finish preparing its files and ask you for a Linux username and password. This account is independent of your Windows user.

When typing the password, you won’t see asterisks or any other characters on the terminal. The keyboard isn’t broken: this is standard Linux behavior. Type the password and press Enter.

On Ubuntu or Debian, it is advisable to update the package list and installed applications:

sudo apt update
sudo apt upgrade

The first command fetches information about available versions. The second installs the updates, so they are different operations even though they are usually run one after the other.

Checking and managing WSL

You can manage WSL from PowerShell, Windows Terminal, or the command prompt. These are the commands you will use most frequently:

New distributions are installed in WSL 2 by default. If you have an older installation on WSL 1, you can convert it by specifying the name shown by wsl --list --verbose:

wsl --set-version Ubuntu 2

The conversion can take several minutes and requires free disk space. To set WSL 2 as the default version for distributions you install later, use:

wsl --set-default-version 2

Working with Windows and Linux files

WSL allows access to files on both systems, but it is important to know where to save each project to avoid performance losses.

From Linux, Windows drives are mounted within /mnt. For example, the root of the C: drive is available at:

cd /mnt/c

From Windows File Explorer, you can type \\wsl$ in the address bar to see the installed distributions. You can also use an explicit path like \\wsl.localhost\Ubuntu\home\<username>.

The full recommendation is explained in the WSL file system documentation.

Using WSL with Visual Studio Code

Visual Studio Code has an official extension called WSL that allows you to keep the editor interface on Windows while the code, terminal, Git, and development tools run inside Linux.

1. Install Visual Studio Code on Windows and enable the option to add code to the PATH.
2. Install the WSL extension published by Microsoft.
3. Open the distribution, navigate to the project folder, and run:

code .

VS Code will open that folder in a session connected to WSL. Some extensions, such as those for Python, debugging, or linting, must also be installed within the distribution; the editor itself will prompt you when necessary.

You can expand on this setup in the official VS Code guide with WSL.

Using WSL with Docker

Docker Desktop can use WSL 2 as its engine to run Linux containers. This way you can launch docker from your distribution and work with the same files and tools used by the project.

After installing Docker Desktop, enable the WSL 2 based engine and enable integration for the distribution you want to use. Docker Desktop is not required to use WSL; you only need to install it if you plan to work with containers.

The configuration may change between versions, so it is best to follow the Docker Desktop documentation for WSL.

Limiting resources for WSL 2

WSL 2 automatically manages the memory and processors of its virtual machine. Normally you don’t need to change anything, but you can set global limits using the %UserProfile%\.wslconfig file if a development environment consumes too many resources.

Open the file from PowerShell with:

notepad "$env:USERPROFILE\.wslconfig"

For example, this configuration limits WSL 2 to 4 GB of memory and two processors:

[wsl2]
memory=4GB
processors=2

After saving the file, stop WSL to apply the changes:

wsl --shutdown

Do not set limits too low as they can slow down compilations, databases, and containers. Use this option only if you have a real resource consumption problem.

Common troubleshooting

Installation hangs at 0%

If the distribution download does not start, Microsoft recommends downloading it from the web source instead of using the Microsoft Store:

wsl --install --web-download -d Ubuntu

WSL 2 cannot start the virtual machine

Errors like 0x80370102 usually indicate that the Virtual Machine Platform feature is not active or that virtualization is disabled in the BIOS or UEFI.

First check the Performance > CPU tab in Task Manager. The virtualization section should show Enabled. If not, consult your computer manufacturer’s instructions before modifying the BIOS or UEFI.

WSL or the kernel are outdated

Update WSL and restart its environment with:

wsl --update
wsl --shutdown

This updates WSL, but not the Ubuntu or Debian packages. For those packages, you must use apt update and apt upgrade within the distribution.