If you work in software development, system administration, or simply enjoy tinkering with Linux, WSL2 has become an almost indispensable tool on Windows . It allows you to have a complete GNU/Linux environment, with a real kernel, directly integrated into your computer without struggling with cumbersome virtual machines or dual-boot configurations.
In this guide, we'll see how to install and configure WSL2 step by step on Windows 10 and Windows 11 , what requirements you must meet, how to choose the best Linux distribution for your needs, how to manage multiple distributions, and what best practices to follow to get the most out of it and avoid common errors during installation.
What is WSL and what advantages does WSL2 have?
WSL (Windows Subsystem for Linux) is a feature of Windows that allows you to run GNU/Linux distributions such as Ubuntu, Debian, Kali or Alpine directly on Windows , using their usual tools and commands (bash, ssh, git, grep, etc.) without the need for a traditional virtual machine.
With the arrival of WSL2, Microsoft took a significant leap forward, moving from a compatibility layer to running a real Linux kernel within a lightweight virtual machine . This resulted in vastly improved file system and network performance, as well as virtually complete compatibility with Linux system calls.
Among the most interesting advantages of WSL2 are much faster disk and network access, optimized memory usage, and very convenient integration between Windows and Linux files , allowing you to work on the same projects from both worlds without any hassle.
For modern development environments, WSL2 is ideal because it fits perfectly with Docker container-based workflows, CI/CD, web development, and data science , allowing your laptop environment to closely resemble your production servers (which are usually Linux).
Prerequisites for installing WSL2
Before you start running commands like crazy, it's worth checking that your version of Windows is compatible with WSL2 and that you have virtualization enabled in the BIOS , because otherwise you'll run into some pretty confusing errors.
Depending on the operating system, WSL2 is available on Windows 10 and Windows 11 , but with fairly specific minimum versions. On Windows 10, you need at least version 1903 with build 18362 for basic WSL, and to take full advantage of WSL2, version 2004 with build 19041 or higher is recommended. On Windows 11, virtually all modern editions include WSL2 by default.
To check your exact version, press Win+R, type "winver", and press OK . A small window will open showing your Windows edition, version, and build. If you're missing any, you'll need to update Windows from Settings > Update & Security.
In addition to the Windows version, hardware virtualization must be enabled in your computer's BIOS/UEFI . If it isn't, WSL2 won't be able to boot, and you'll see errors like 0x80370102 or messages about Hyper-V. The option may have different names depending on the manufacturer (Intel VT-x, Intel Virtualization Technology, AMD-V, SVM, etc.), but the idea is the same: enter the BIOS, locate the CPU or security section, and enable virtualization.
Another important detail is that WSL2 is not supported in Windows 10 S and there may be limitations in some LTSC editions or in Windows Server with enterprise policies . In those cases, you will often have to resort to manually installing distributions using appx or tar files instead of the Microsoft Store.
Quick method: Install WSL2 with a single command
In modern versions of Windows, Microsoft has greatly simplified the process, so much so that you can have WSL and a functional Linux distro with a single command , without having to check any boxes in the Windows features.
The recommended method is to open PowerShell or Command Prompt as administrator (right-click on the icon and select "Run as administrator") and run:
wsl --install
This command automatically enables the necessary features of Windows Subsystem for Linux and the Virtual Machine Platform , downloads the Linux kernel for WSL2, and by default installs Ubuntu as the initial Linux distribution on your system.
When the process is complete, Windows will prompt you to restart. After the first restart, when you open the Linux distribution for the first time, you'll see an installation and user creation message while the files are being extracted and the environment is being prepared. This initial launch takes a little while, but subsequent launches are virtually instantaneous.
If you prefer to use a different distribution than Ubuntu from the start, you can specify this with the -d parameter . For example, to install Debian directly:
wsl --install -d Debian
At any time you can view the list of official distributions available for installation with:
wsl --list --online
WSL2 Step-by-Step Manual Installation
The quick command is great, but on machines with older versions of Windows 10, on Windows Server, or when there are restrictive corporate policies , you may have to follow the traditional step-by-step manual procedure.
The first step is to enable the optional "Windows Subsystem for Linux" feature . To do this, open PowerShell as administrator and run:
dism.exe /online /enable-feature /featurename:Microsoft-Windows-Subsystem-Linux /all /norestart
This prepares your system to run basic WSL (WSL1). If you only wanted that version, you could restart now and then proceed directly to installing a distribution. However, to use WSL2, it's best to follow these steps before or immediately after restarting.
The second step is to enable the "Virtual Machine Platform" feature , which is the foundation upon which the WSL2 Linux kernel runs. Again, in PowerShell as administrator, run:
dism.exe /online /enable-feature /featurename:VirtualMachinePlatform /all /norestart
After enabling these two features, restart your computer so that Windows can finish applying the changes . This is crucial, because if you don't restart, you'll start seeing strange errors when using WSL.
Once restarted, you need to install or update the Linux kernel package for WSL . Microsoft offers an MSI installer that downloads the latest kernel version. You can get it from the official WSL GitHub page or from the Microsoft documentation, download it, and run it like any other installer, accepting elevated privileges when prompted.
Once the kernel package is installed, it's a good idea to set WSL2 as the default version for all new distributions you install . You can do this with the following command in PowerShell or CMD:
wsl --set-default-version 2
From that moment on, every new distro will be created directly in WSL2 , although you can always force any specific distribution to WSL1 or WSL2 later with the version change command.
Install a Linux distribution for WSL2
With WSL enabled and WSL2 set as the default, the next step is to choose and install your favorite GNU/Linux distribution . Here are several options depending on whether you can use the Microsoft Store or need to install it manually.
In the most convenient scenario, you open the Microsoft Store and search for "Linux" or directly for the distro you want : Ubuntu, Debian, Kali Linux, Fedora, Arch, openSUSE, Alpine, Oracle Linux, Rocky, AlmaLinux, etc. Each one has its own page and is installed with the "Get" button, just like any other app.
Clicking "Get" will download the files from the store, and once the installation is complete, you'll see the "Start" button . The first time you open it, a console will appear with an internal installation process, and then you'll be prompted to create a username and password for that Linux system.
If you can't use the store (for example, on Windows Server, LTSC versions, or computers with corporate policies that block the Microsoft Store ), you can also download the .appx packages for the distributions directly from the official Microsoft links. These packages are installed with the command:
Add-AppxPackage .\nombre_de_la_distro.appx
Another alternative, very useful when Microsoft provides direct URLs, is to use curl.exe or Invoke-WebRequest to download the package from PowerShell . For example, you could do something like this:
Invoke-WebRequest -Uri https://aka.ms/wslubuntu2204 -OutFile Ubuntu.appx -UseBasicParsing
Once the appx package is downloaded and installed, simply double-click on the file or launch the distribution from the Start menu to complete the configuration and create your Linux user.
First boot: create user and configure the distro
When you boot a newly installed distribution for the first time, WSL displays a message explaining that it is installing the system and that it may take a few minutes . This is normal; it is decompressing the rootfs and preparing the environment.
When it's finished, you'll see a notification like this:
Installing, this may take a few minutes...
Please create a default UNIX user account.
Enter new UNIX username:
At that point you will need to choose a username for your Linux account, which will be the default user you log in to that distro with and which will usually have sudo permissions.
It is advisable that the username be in lowercase, without accents or special charactersAnd it doesn't have to match your Windows username. That same name will be used for your home folder, for example. /home/manuel if you chose "manuel".
Next, the system will ask you to enter a password for that user and confirm it . It is crucial that you remember these credentials, because you will use them for operations with sudo and to access the environment if you activate additional services.
Once the user is created, you'll have your fully functional GNU/Linux distribution running within Windows . From there, you can update packages with apt, dnf, or pacman, depending on the distribution, and install development tools, web servers, databases, and more.
Basic commands for managing WSL and WSL2
WSL is primarily managed using the wsl.exe command from PowerShell or Command Prompt . There are several commands you should be familiar with to know what you have installed and which version each distribution is using.
To list available distributions and view their status and version, you can use the -l -v parameter (or the long form –list –verbose):
wsl -l -v
In the output you will see columns with the name of the distro, whether it is running or stopped, and whether it is version 1 or 2. If you have migrated from WSL1, here you will check if the conversion has been applied correctly.
If you want to change the WSL version of a specific distribution, use the command –set-version specifying the distro and version 1 or 2:
wsl --set-version Ubuntu 2
This will launch a conversion process that may take a while depending on the size of your distro's file system. It usually takes several minutes, so be patient. When it's finished, if you run it again... wsl -l -vYou should see the VERSION column with a 2.
You can also set the default version for new installations with `--set-default-version` , as we saw earlier:
wsl --set-default-version 2
To select which distribution will be the default when you only type wsl without parameters, Use the command –set-default or its alias -s indicating the name of the distro:
wsl --set-default Debian
If at any point you need to boot a specific distribution without changing the default, you can use the -d parameter :
wsl -d Kali-Linux
To execute a specific Linux command from PowerShell or CMD without opening an interactive session , simply do the following:
wsl ls -la
This will execute ls -la in the default distro and will return the output directly to your Windows terminal, which is very convenient for small scripts or automated tasks.
Choosing, installing, and managing multiple distributions in WSL2
One of the great things about WSL is that you're not limited to a single distribution . You can install as many as you want and use them for different projects or tests without them interfering with each other.
The most common approach is to use Ubuntu or Debian as a base for general development , but you can add Kali for security purposes, AlmaLinux or Rocky to simulate RHEL-type environments, openSUSE to try a different philosophy, or minimalist distros like Alpine for containers.
To see what quick installation options are currently available, use the command that lists online distributions :
wsl --list --online
The output will show you names of distros ready to use with wsl --install -d NombreDistroIf you choose a paid one in the Microsoft Store, you'll see a warning, but many of them also have alternative free download channels outside the store.
Once you have several distributions installed, You can assign the one you use most often as the default for your everyday commands. and boot the rest from Windows Terminal, from the Start menu (searching for "Ubuntu", "Debian", etc.) or with wsl -d when you need something specific.
If at any point one of the distributions becomes unnecessary or you only want it for a specific test, you can uninstall it from Windows Apps & Features or using the unregistration command (which removes the entire distribution and its data). This way you keep your system clean and free of environments you don't use.
Integration with Docker, VS Code, and development workflows
Where WSL2 truly shines is when you start integrating it into your daily development workflow with modern tools , especially with Docker and Visual Studio Code.
In the case of Docker, Docker Desktop for Windows allows you to use WSL2 as a backend , instead of the classic Hyper-V. This greatly improves container performance and simplifies image and volume management, since they run directly within the same Linux distribution you use for development.
For code editors, Visual Studio Code offers the Remote – WSL extension , which allows you to open a folder on your Linux distribution as if you were working natively there. In practical terms, this means that all code analysis, debugging, integrated terminal, and other tools run within WSL2 , while the graphical editor runs in Windows.
This combination makes it much easier to work with microservices, APIs, Node.js, Python, Go or Ruby projects, Docker applications and cloud deployments (AWS, Azure, etc.), because you test your applications almost exactly the same as on a real Linux server.
In professional or corporate environments, teams specializing in custom software, cybersecurity, or cloud services leverage WSL2 to build continuous integration and deployment pipelines, automate testing, and work with artificial intelligence agents or data analysis tools without leaving their Windows workstation.
Accessing and sharing files between Windows and Linux
One of WSL's strengths is that the Windows and Linux file systems are integrated quite transparently , allowing you to move projects back and forth without too much friction.
From Linux, Your Windows drives are automatically mounted under the /mnt pathFor example, drive C will look like /mnt/c, the D as /mnt/dand so on. If you go into /mnt/c/Users/TuUsuario You will be able to manipulate your Windows documents, repositories, and files from the Linux terminal.
Conversely, you can also do this from Windows File Explorer access your Linux distro's files nativelyWindows creates special paths and environment variables to reach your /homeFurthermore, with WSL2 it is possible to navigate through the browser using special network paths that point to the distro's file system.
That said, in terms of performance, It is recommended that development projects reside in the file system of the Linux distro itself. (for example, /home/tuusuario/proyecto) and not in /mnt/cbecause access through the Windows file system is usually much slower, especially if you perform many small operations.
This file integration is especially useful when you want to edit documents with Windows graphical applications and run scripts or commands on those same files from Linux , without having to duplicate content or create complex synchronization mechanisms.
Best practices, performance and security in WSL2
Once you have WSL2 up and running and one or more distributions up and running, it's advisable to apply a series of best practices to keep the environment stable, secure and performing well , especially if you plan to use it intensively.
First, keep the WSL kernel and the distributions themselves up to date . You can update the WSL component from Windows with:
wsl --update
And then, within the distro, use the corresponding package manager (apt update && apt upgrade, dnf upgradeetc.) to ensure that all software is up to date and has security patches applied.
From a security standpoint, although WSL2 runs within a lightweight virtual machine, it is still a Linux environment with services, ports, and processes that may have vulnerabilities . It is important to use a non-root user for daily operations, configure firewalls if you expose services, and avoid leaving daemons listening on all interfaces without control.
For equipment commonly used for heavy-duty development, data science, or containers, you might be interested in Adjust WSL2 resource consumption (memory, CPU, swap) using the configuration file .wslconfig In Windows, you can limit how much RAM and how many cores the WSL virtual machine can use.
Regarding file system performance, It is preferable to work within the distro's native storage For large projects and code repositories. Access to Windows folders under /mnt It works well for specific tasks, but in scenarios with millions of files or many I/O operations it can be significantly slower than WSL1.
And, although it may seem obvious, it's worth remembering that before making serious changes or risky tests, it's advisable to have backups of your most important data , especially if you're going to play with scripts, containers, or low-level tools in the Linux environment.
Common errors when installing WSL2 and how to fix them
During the installation or configuration of WSL2, you may encounter some common errors that are frequently repeated by users . Knowing about them beforehand can save you time and frustration.
One of the most common errors is 0x8007019e , which usually indicates that the WSL subsystem is not enabled correctly. The solution involves re-running the WSL feature activation command using DISM or from "Turn Windows features on or off" and restarting.
Another common issue is seeing a message stating that WSL2 needs a kernel component update . This is usually resolved by downloading the latest Linux kernel update package for WSL from the Microsoft website and installing it manually.
Errors 0x80370102 and 0x80070003 can be related to disabled or misconfigured virtualization , or to Windows' default storage being on a different drive. In the first case, you'll need to enter the BIOS and enable virtualization; in the second, check in Settings > System > Storage where new apps are being saved and change it if necessary.
When a distro installation doesn't finish successfully, it's advisable to consult the official WSL troubleshooting guide , where Microsoft details many of these error codes and proposes specific steps to resolve them, including special cases for Windows Server or Core installations.
If your problem is that the command wsl --install It doesn't exist or it's faulty, it's likely that your version of Windows may be too old to support that simplified methodTherefore, you will have to follow the manual installation path by enabling WSL and the Virtual Machine Platform, installing the kernel, and then adding the distros one by one.
In general, spending some time reviewing version requirements, virtualization, and enabled features usually resolves most errors without the need for drastic measures , and once WSL2 starts up correctly, it behaves quite stably.
WSL2 has established itself as a very powerful solution for those who need to combine the Windows and Linux worlds on the same machine, and with the steps and recommendations above you should be able to install, configure and use it daily with ease, taking advantage of its benefits in performance, compatibility and productivity without falling into the typical problems of traditional virtual machines.