Install and Use Windows Subsystem for Linux (WSL) for Dev Workflows
Difficulty: Beginner | Time Required: 20-30 minutesWS L gives you a real Linux environment inside Windows. With WSL 2, you get a full Linux kernel, faster performance, and seamless toolchains for development. This guide walks you through installing and using WSL for everyday development tasks on Windows 10 or Windows 11.
Introduction
If you build web apps, run Python, Node, Rust, or containerized projects, having Linux tooling alongside Windows can be a game changer. WSL lets you run Linux commands, editors, and utilities without dual-booting or managing a VM. On Windows 11, WSL 2 includes improved performance and even GUI app support (WSLg). On Windows 10, you can still have a robust WSL 2 setup, though GUI support is limited and may require extra config.Prerequisites
Quick walkthrough
- A PC that supports virtualization (Intel VT-x or AMD-V) and virtualization is enabled in BIOS/UEFI.
- Administrative access on Windows.
- An active internet connection.
- Windows 10 version 2004 (May 2020 Update) or newer, or Windows 11.
- Optional but recommended: Windows Terminal and a code editor (e.g., Visual Studio Code) for a nicer workflow.
Notes:
- WSL 2 requires a real Linux kernel. Windows 11 ships with this, and Windows 10 users may need to install the Linux kernel update package from Microsoft.
- If you plan to use Docker Desktop, enabling WSL 2 as the backend is highly recommended.
Step-by-step Instructions
Follow the path that matches your Windows version.A) Windows 11 (easiest path)
- Open PowerShell as Administrator and install WSL with default distro
- Run:
wsl --install - This command installs the Windows Subsystem for Linux, the Virtual Machine Platform, sets WSL 2 as default, installs a Linux distribution (usually Ubuntu), and configures your environment.
- Reboot when prompted.
- Start your Linux distro
- From the Start menu, launch “Ubuntu” (or the distro installed by the command).
- Create your Linux user account and password when prompted.
- Update and upgrade your Linux packages
- In the Linux terminal:
sudo apt update
sudo apt upgrade -y - Optional: Install Windows Terminal and VS Code integration
- Windows Terminal provides a better tabbed terminal experience.
- In Windows, install VS Code and the Remote - WSL extension if you plan to edit code inside WSL.
- Verify WSL version and distro status
- In PowerShell:
wsl -l -v - You should see your distro listed with Version 2 (indicating WSL 2).
B) Windows 10 (19041+ / 2004 era) — manual path
- Check system readiness
- Ensure virtualization is enabled in BIOS/UEFI. Quick check: open Task Manager → Performance → Virtualization should say Enabled.
- Enable WSL and Virtual Machine Platform features
- Open PowerShell as Administrator and run:
dism.exe /online /enable-feature /featurename:Microsoft-Windows-Subsystem-Linux /all /norestartdism.exe /online /enable-feature /featurename:VirtualMachinePlatform /all /norestart- Restart your PC when prompted.
- (Optional but recommended) Install the WSL 2 Linux kernel update package
- Download and install the package from Microsoft: “WSL 2 Linux kernel update package for x64 machines.”
- This is required for WSL 2 on some Windows 10 builds.
- Set WSL 2 as your default version
- In PowerShell (Admin):
wsl --set-default-version 2 - Install a Linux distribution
- Open the Microsoft Store, search for “Ubuntu” (or another distro like Debian, Fedora), and click Install.
- Complete initial distro setup
- Launch the distro from the Start menu, create a user, and set a password.
- Update/upgrade and basic dev setup
- In the Linux terminal:
sudo apt updatesudo apt upgrade -y- Install common Dev tools if you like, e.g.
sudo apt install -y build-essential git curl wget unzip - Optional: Enable Docker Desktop with WSL 2 backend
- Install Docker Desktop for Windows and in its settings choose "Use WSL 2 based engine."
- This gives you Docker inside Windows using the WSL 2 backend.
C) Quick-start cheat sheet (works on both OS paths)
- Check installed distros and versions:
wsl -l -v - Run a command in a specific distro:
wsl -d Ubuntu -- echo Hello from WSL - Launch a Linux shell from Windows Terminal or cmd:
wsl - Install additional distros from Store and switch between them:
wsl --set-default-version 2then usewsl -d <distro-name>
Tips and Troubleshooting Notes
- If you see “The virtual machine could not be started” when trying to run WSL 2, double-check that virtualization is enabled in BIOS and that the Virtual Machine Platform feature is enabled. A restart is often needed after enabling features.
- If a distro remains in version 1 after
wsl --set-default-version 2, set the version for the specific distro:
wsl --set-version Ubuntu-20.04 2 - Some older Windows 10 builds require you to install the Linux kernel update package manually. If you’re stuck, download and install the “WSL 2 Linux kernel update package” and then try setting the default version again.
- Windows Store issues? If the distro install from the Store hangs, try resetting the Microsoft Store or run the Store app troubleshooter, then retry the install.
- For GUI Linux apps on Windows 11 (WSLg)
- WSL 2 on Windows 11 supports running Linux GUI apps with WSLg. Just install GUI-capable apps as you would in Linux; they should display natively.
- On Windows 10, GUI app support isn’t officially included in WSL out of the box. You can still run GUI apps using an X server (like VcXsrv or Xming), but that’s a bit more setup.
- If you plan to Dockerize locally, Docker Desktop with WSL 2 backend provides a smoother experience and file-system performance benefits over older setups.
- File system performance tips
- Keep project files in the Linux filesystem (the distro’s ext4) for best performance, or use a shared /mnt/c path with care to performance.
- You can access Windows files under /mnt/c, but operations on those files may be slower than within the Linux filesystem.
Conclusion
WSL brings a native-like Linux dev environment to your Windows PC without rebooting or running a full VM. With WSL 2, you gain a real Linux kernel, faster performance, and strong interoperability with Windows tools. Whether you’re building web apps, scripting, or working with Linux-centric toolchains, WSL makes cross-platform development smooth and accessible.Key takeaways:
- WSL 2 provides a real Linux kernel and improved performance on Windows.
- It’s available on Windows 11 with a simple install, and on Windows 10 with a few extra steps (kernel update and feature enabling).
- You can run Linux tools directly in Windows, and optionally integrate with Docker Desktop and VS Code for a powerful dev workflow.
- GUI app support is available on Windows 11 via WSLg; Windows 10 users can still run CLI tools effectively and may use an X server for GUI apps.
This tutorial was generated to help WindowsForum.com users get the most out of their Windows experience.
Last edited:
