Want a Linux development environment without dual-booting or a heavy virtual machine? WSL2 (Windows Subsystem for Linux 2) runs a full Ubuntu or other distro right inside Windows, starts in about a second, and lets you reach Windows files, run Docker, and use VS Code remote development. This guide covers install, configuration, and daily use from scratch.

What WSL is and why WSL2

WSL is Microsoft's Linux subsystem on Windows. WSL1 is a translation layer; WSL2 is a real, lightweight virtual machine built on the Hyper-V kernel, running a full Linux kernel. It has the best compatibility and the highest file-system performance (except when crossing into Windows files).

Who it is for.

  • Developers running Node, Python, Go, Rust, Docker, or Linux-only CLI tools.
  • Ops or SREs reproducing server environments locally.
  • Students or hobbyists learning Linux commands at zero cost.

It is not for a full desktop to play games or for drivers that only ship as closed-source Linux binaries.

Requirements: Windows 10 2004 or later, or Windows 11 (Home included, no Pro needed).

  1. Open PowerShell or Windows Terminal as administrator and run.
wsl --install

This single command enables the needed Windows features, installs the default Ubuntu, and pulls the latest kernel.

  1. Reboot.
  2. Open Ubuntu from the Start menu and set a username and password (for Linux, unrelated to your Windows password).
  3. Done. Run uname -a in the terminal to see the Linux kernel version.

To install another distro, run wsl --list --online for the list, then wsl --install -d Debian for Debian.

Manual enable (if the one-line install fails)

  1. In admin PowerShell.
dism.exe /online /enable-feature /featurename:Microsoft-Windows-Subsystem-Linux /all /norestart
dism.exe /online /enable-feature /featurename:VirtualMachinePlatform /all /norestart
  1. Reboot.
  2. Download and install the WSL2 Linux kernel update package (search "WSL2 kernel" on Microsoft's site).
  3. Set WSL2 as default with wsl --set-default-version 2.
  4. Install Ubuntu from the Microsoft Store, or wsl --install -d Ubuntu.

If the feature checkbox is greyed out, BIOS virtualization is likely off; start with the Windows Sandbox and Hyper-V article.

Common configuration

Swap to a faster package source (apt)

Edit /etc/apt/sources.list on Ubuntu and switch to a China-based mirror such as USTC, Aliyun, or Tsinghua, then run sudo apt update && sudo apt upgrade -y. New users can search "Ubuntu 22.04 Tsinghua source" and paste.

Reach Windows files

  • From Linux, Windows lives under /mnt/c, /mnt/d, and so on, for example /mnt/c/Users/yourname/Desktop.
  • From Windows, type \\wsl$\Ubuntu\ in File Explorer's address bar.

Cross-system reads and writes are slow, so keep large project files in the Linux home directory (~, that is /home/yourname), not in /mnt/c.

Cap memory and CPU (avoid eating all RAM)

In your user folder (C:\Users\yourname) create a file named .wslconfig with this.

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

Save, then run wsl --shutdown to apply on next start. This matters most when C is low on space.

Graphical apps (GUI)

WSL2 supports native Linux GUI through WSLg, built into Windows 11. Just run sudo apt install gedit; the gedit window pops up natively, no extra X server needed.

Docker

Install Docker Desktop for Windows and tick "Use WSL 2 based engine" in settings. Then docker inside WSL talks directly to it, far lighter than running Docker inside a VM.

WSL vs dual-boot vs virtual machines

OptionStartupPerformanceTalks to WindowsBest for
WSL2InstantNear native (in Linux)StrongDev, command line first
Dual bootRebootNativeNo, separate OSNeeds exclusive hardware
Hyper-V/VMwareSlowReducedLimitedFull standalone OS

In one line: use WSL2 for development, a VM for full isolation (see Run Virtual Machines on Windows with Sandbox and Hyper-V), and dual boot only when you must own the hardware.

Common problems

  • wsl --install errors or hangs. Confirm the Windows build is new enough, use admin rights, or download the kernel package manually on a corporate network.
  • WSL2 says virtualization is not enabled. Turn on VT-x/SVM in BIOS; see the Windows Sandbox and Hyper-V article.
  • 0x80370102 will not start. The Hyper-V or Virtual Machine Platform feature is off, or BIOS virtualization is disabled.
  • wsl command not found. The Windows version is too old; upgrade or clean-install Windows 11.
  • Network down or apt slow. Switch to a local mirror, or check corporate proxy; the DNS and proxy ideas in Browser Can't Open Web Pages, but WeChat Works help.
  • WSL2 nested virtualization. The November 2026 cumulative update (KB5127936) fixed a prior nested-virtualization fault, so keep current.

Advanced tips

  • VS Code remote development. Install the WSL extension and open project folders right inside the Linux environment.
  • Windows Terminal. Free from the Microsoft Store; one tabbed window for PowerShell, CMD, and Ubuntu beats everything else.
  • systemd. Newer WSL2 enables systemd by default, so more Linux services run.

Mount a USB drive and switch distros

  • Reach a host USB or external disk. WSL2 does not see USB devices by default. The simplest route is to drop files on a Windows drive (D, for example) and read them from /mnt/d. To mount USB directly, forward it from Windows with the usbipd tool using usbipd wsl attach --busid 1-2; it is fiddly, so beginners can skip it.
  • Switch the default distro. wsl --setdefault Debian makes Debian the one wsl opens.
  • Remove a distro. wsl --unregister Ubuntu deletes that distro and its data; make sure nothing is inside first.
  • Export and import. wsl --export Ubuntu ubuntu.tar backs up; wsl --import restores on another machine, handy for moving a dev environment.