On a current Windows build you can install WSL with one command: open PowerShell as administrator, run wsl --install, restart, and finish the Ubuntu setup. That command enables the required Windows features, installs the Linux kernel, sets WSL 2 as the default, and installs Ubuntu. Microsoft lists the requirement as Windows 10 version 2004 (Build 19041) or later, or Windows 11.
This guide walks through that install, the manual steps for older Windows builds, upgrading from WSL 1 to WSL 2, customization, Docker, GUI apps, and troubleshooting.
🧩 What Is WSL? (and WSL 1 vs WSL 2)
Windows Subsystem for Linux runs a Linux distribution such as Ubuntu or Debian directly on Windows, without dual booting or managing a separate VM. WSL 1 translates Linux system calls into Windows calls through a translation layer (lxcore.sys). WSL 2 runs a real Linux kernel inside a lightweight managed VM, which gives it full system call compatibility and lets you run tools like Docker.
| Feature | WSL 1 | WSL 2 |
| Kernel | Translation layer | Real Linux kernel in a managed VM |
| System call compatibility | Partial | Full |
Speed on files inside Linux (/home) |
Slower | Faster |
Speed on Windows files (/mnt/c) |
Faster | Slower |
| Docker Desktop, WSLg | No | Yes |
Pick WSL 2 unless your files live on the Windows drive and you work on them from Linux. That's the one case where WSL 1 still wins, and you can run both versions side by side on different distros.
🎯 Uses and Benefits of WSL
- Running Linux applications on Windows: Test cross-platform applications without leaving Windows.
- Developing cross-platform apps: Switch between Windows and Linux environments quickly.
- Using Linux command-line tools: Access grep, sed, awk, and other tools unavailable natively in Windows.
- Enhancing Windows with Linux tools: Combine Linux utilities with your Windows workflow.
- Accessing the Linux file system from Windows: Work seamlessly between the two file systems.
- Running Docker containers: WSL 2 supports Docker Desktop as its backend.
- Learning and experimenting with Linux: Try Linux without installing a separate OS.
- Faster performance and reduced resource consumption: WSL 2 is faster than WSL 1.
- Easy installation and setup: One command on current Windows builds.
- Free and open-source: No license cost.
📋 Before You Install WSL
- Windows 10 version 2004+ or Windows 11 for the one-command install. Run
winverto check. - Hardware virtualization turned on in the BIOS/UEFI. Task Manager shows "Virtualization: Enabled" on the Performance tab under CPU. If you need a deeper walkthrough on enabling virtualization and setting up a VM, see how to set up a virtual machine.
- At least 4 GB of RAM and a 64-bit Windows install.
- Administrator rights for the install itself. Day-to-day use doesn't need them.
You don't need to enable or disable Developer Mode, and you don't need the full Hyper-V role. WSL 2 uses the Virtual Machine Platform component, which works on Windows 10 Home. Windows Terminal and VS Code are optional extras.
⚡ How to Install WSL with One Command
Open PowerShell or Windows Terminal as administrator and run:
wsl --installRestart when prompted. Ubuntu then asks for a Linux username and password, separate from your Windows account; sudo uses that password.
For a different distribution, list the options and name one:
wsl --list --online
wsl --install -d DebianUbuntu is the safe default because most tutorials assume it. Debian is lighter.
🔧 Manual Install on Older Windows Versions
If wsl --install isn't recognized, use Microsoft's manual installation steps. In an admin PowerShell:
dism.exe /online /enable-feature /featurename:Microsoft-Windows-Subsystem-Linux /all /norestart
dism.exe /online /enable-feature /featurename:VirtualMachinePlatform /all /norestartRestart, install the Linux kernel update package from that Microsoft page, run wsl --set-default-version 2, and install a distro from the Microsoft Store. Launch the distro and follow its setup wizard to create your Linux user.
🔄 How to Upgrade from WSL 1 to WSL 2
Check which version each distro uses:
wsl --list --verboseThe VERSION column shows 1 or 2. Use the exact name from the NAME column to convert:
wsl --set-version Ubuntu 2
wsl --set-default-version 2The first command converts the distro, which takes several minutes for large ones. The second makes future installs use WSL 2.
✅ How to Verify WSL Is Working
Run wsl --status to see the default distro and version, and wsl --version to see the WSL and kernel versions. Then open your distro and try uname -a, pwd, and ls. If uname -a prints a kernel string containing "microsoft-standard-WSL2", you're on WSL 2. If you want a clean Windows environment to test these commands without touching your main machine, a Windows 10 VPS gives you a disposable desktop. For checking your Windows build before installing, see how to find OS version with command line.
🎨 Customizing WSL/WSL2
- Changing the default distribution:
wsl --set-default <distribution name>. - Changing the default user: Edit
/etc/wsl.confand adduser=<username>. - Configuring the Linux environment: Edit
.bashrcor.zshrcin your home directory. - Installing additional software: Use the package manager — e.g.,
sudo apt install giton Ubuntu. - Configuring network settings: Edit
/etc/resolv.conffor DNS settings. - Mounting Windows drives: Use
/mnt— e.g.,sudo mount -t drvfs D: /mnt/d. - Accessing files and folders: By default, WSL sees Windows drives under
/mnt/c. - Installing Windows Terminal: Download it from the Microsoft Store to manage multiple tabs and windows.
📂 Files, Performance, and VS Code
Linux sees your Windows drives under /mnt/c, and File Explorer reaches Linux files at \\wsl$ (or run explorer.exe . inside Linux). When you work with Linux tools, keep project files in the Linux file system, such as ~/projects. On WSL 2, tools like npm install run noticeably slower against /mnt/c.
For editing, install the WSL extension in VS Code, then run code . from a Linux folder. The VS Code server runs inside WSL, so your extensions, terminals, and debuggers use Linux binaries and paths while the editor window stays on Windows. For a full walkthrough of installing VS Code on Ubuntu, see how to install Visual Studio Code on Ubuntu. For heavy workloads that need guaranteed resources beyond a standard VPS, a Windows dedicated server is the next step up.
WSL also provides native SSH support. Connect to a remote server with ssh user@192.168.1.10. To run a Windows app from inside WSL, use cmd.exe /c "start notepad". For generating SSH keys inside WSL, see how to create SSH key in Windows.
🐳 How to Use Docker with WSL 2
Docker Desktop uses WSL 2 as its backend on Windows. Docker's documentation requires at least WSL version 2.1.5 and recommends the latest. Run wsl --update first, then:
- Install Docker Desktop and open Settings.
- Under General, make sure "Use the WSL 2 based engine" is checked.
- Under Resources, then WSL Integration, turn on each distro that should get the
dockercommand. - Apply and restart, then run
docker run hello-worldinside the distro.
If docker isn't found, the distro is probably still on WSL 1 or has integration turned off.
🖥️ How to Run Linux GUI Apps with WSLg
WSLg is built into WSL 2 on Windows 11 and Windows 10 Build 19044 or later. Install an app and launch it from the shell:
sudo apt update
sudo apt install gedit -y
geditThe window opens on your Windows desktop, and current GPU drivers add hardware acceleration. An X server such as VcXsrv is only worth setting up on older builds without WSLg.
🚨 Common WSL Problems and Fixes
| Symptom | Fix |
| Error 0x80370102 or "virtualization not enabled" | Enable Intel VT-x or AMD-V in the BIOS/UEFI and confirm Virtual Machine Platform is on in Windows Features. |
wsl --install not recognized |
Your build is older than 2004. Update Windows or use the manual steps. |
| Store download stalls | Run wsl --install --web-download -d Ubuntu. |
| Distro stuck on WSL 1 | Run wsl --set-version <Distro> 2 and check virtualization. |
| No internet or DNS failures inside Linux | Run wsl --shutdown and reopen. VPNs are a common cause; see Microsoft's WSL troubleshooting guide. |
| Firewall or antivirus blocking WSL | Add exceptions for WSL in your security software settings. |
| Installation logs needed | Check C:\Users\<Username>\AppData\Local\Temp\ for installation logs. |
🔄 How to Update, Export, and Uninstall WSL
wsl --update updates WSL and its kernel. To back up or move a distro, export it to a tar file and import it elsewhere:
wsl --export Ubuntu D:\backup\ubuntu.tar
wsl --import UbuntuCopy D:\WSL\UbuntuCopy D:\backup\ubuntu.tarwsl --unregister Ubuntu deletes that distro and everything in it, so export first if you need the files. Reinstall it afterwards for a clean reset. Removing a distro leaves WSL in place. To remove WSL itself, unregister all distros, uninstall "Windows Subsystem for Linux" in Settings then Apps, and turn off the WSL and Virtual Machine Platform features.
📋 WSL Command Cheat Sheet
| Command | What it does |
wsl --install |
Installs WSL and Ubuntu |
wsl --list --online |
Lists distros you can install |
wsl --list --verbose |
Shows installed distros, state, version |
wsl --set-version <Distro> 2 |
Converts a distro to WSL 2 |
wsl --set-default <Distro> |
Sets the default distro |
wsl --update |
Updates WSL and the kernel |
wsl --shutdown |
Stops all distros and the VM |
wsl --unregister <Distro> |
Deletes a distro and its data |
🎓 Conclusion
WSL and WSL 2 let you run Linux applications and commands natively on Windows 10/11. With this guide, you now know how to install it with one command, complete a manual install on older builds, upgrade from WSL 1, customize it, use it with Docker and VS Code, and run Linux GUI apps through WSLg. Whether you're a developer, a system administrator, or someone exploring Linux, WSL 2 is a powerful tool that can greatly enhance your workflow. To put these tools to work on a reliable, always-on Windows environment, explore Windows VPS hosting from MonoVM — full administrator access and dedicated resources.
📚 People Also Read
- How to Learn Linux: 90-Day Roadmap — includes WSL2 setup and essential Linux commands for beginners.
- Troubleshooting RDP Connection Issues on Windows VPS — helpful if you run WSL on a Windows VPS and hit remote access problems.
I'm fascinated by the IT world and how the 1's and 0's work. While I venture into the world of Technology, I try to share what I know in the simplest way with you. Not a fan of coffee, a travel addict, and a self-accredited 'master chef'.