Windows Subsystem for Linux 2 (WSL2) is the practical way to run real Linux tooling on Windows 11 without dual-boot friction or a full Hyper-V VM desktop. WSL2 uses a lightweight utility VM with a real Linux kernel, so compatibility with Node, Python, Docker, and modern dev stacks is excellent—while still letting you keep Windows apps, games, and drivers in the same session.
This guide targets developers, homelab builders, and power users who want Ubuntu (or another distro) on a Windows 11 PC with solid performance and optional Docker integration. We cover the one-command install path, manual feature enablement when needed, .wslconfig tuning, filesystem performance rules, and GPU/CUDA notes for advanced workflows.
Featured-quality depth here means you can treat this as your single reference: from blank machine to docker run hello-world in one sitting.
Before you begin
Prerequisites: Windows 11 (Build 19041+; recent builds simplify install). Administrator account. Virtualization enabled in BIOS/UEFI (Intel VT-x / AMD-V). For Docker Desktop, check WSL2 integration requirements on Docker’s site.
Backups: WSL install does not wipe Windows, but exporting a distro before major changes is wise:
wsl --export Ubuntu C:\backup\ubuntu.tar
Risks: Corporate machines may block optional features or require MDM approval. Mixing project files across /mnt/c/ and the Linux filesystem affects performance—plan directories deliberately.
Understand WSL1 vs WSL2
WSL1 translated syscalls; WSL2 runs a Linux kernel in a VM with fast startup and strong compatibility. Default for new installs is WSL2.
Why WSL2? Better epoll, inotify, and Docker support. The trade-off is networking and file I/O across OS boundaries—mitigated by keeping code inside the Linux filesystem.
Fast install: wsl --install
Open PowerShell as Administrator:
wsl --install
Reboot when prompted. On first launch of Ubuntu, create a UNIX username and password (separate from your Windows password).
Why one command? It enables required Windows features (Virtual Machine Platform, WSL) and installs a default distro when missing—fewer manual toggles than older guides.
Manual path if --install fails
Enable features, then reboot:
dism.exe /online /enable-feature /featurename:Microsoft-Windows-Subsystem-Linux /all /norestart
dism.exe /online /enable-feature /featurename:VirtualMachinePlatform /all /norestart
Set WSL2 as default and update the kernel package:
wsl --set-default-version 2
wsl --update
Why DISM? Some editions or images lack components; DISM is the reliable enabler when Settings toggles are greyed out.
Install or switch distros
List online distros:
wsl --list --online
Install a specific version:
wsl --install -d Ubuntu-24.04
Check what you have and their WSL version:
wsl --list --verbose
Convert an existing distro to WSL2:
wsl --set-version Ubuntu-24.04 2
Why pin versions? Courses and CI often target a specific LTS; naming avoids “latest Ubuntu” drift.
First boot configuration
Inside Linux, update packages:
sudo apt update && sudo apt upgrade -y
Install build essentials if you compile software:
sudo apt install -y build-essential git curl ca-certificates
Why update first? Fresh images ship with stale indexes; updating prevents mysterious apt or SSL errors later.
Filesystem performance: the /mnt/c/ rule
Keep git repositories and node_modules under your Linux home, e.g. ~/projects, not /mnt/c/Users/....
Why? Cross-filesystem I/O is dramatically slower and can break file watchers (hot reload, Jest, Vite). Use VS Code Remote - WSL to edit Linux paths transparently.
Configure .wslconfig on Windows
Create or edit:
C:\Users\YourName\.wslconfig
Example limits:
[wsl2]
memory=8GB
processors=4
swap=4GB
localhostForwarding=true
Restart WSL:
wsl --shutdown
Why cap memory? Docker and WSL share the utility VM; unconstrained RAM use can starve games or browsers on 16 GB machines.
Docker Desktop with WSL2 backend
- Install Docker Desktop for Windows.
- Settings → General → Use the WSL 2 based engine.
- Settings → Resources → WSL Integration → enable your distro.
Verify inside Linux:
docker run hello-world
Why Docker Desktop here? It integrates networking and credentials on Windows while executing containers in WSL2’s VM—less brittle than raw dockerd setup for most users.
GPU and advanced workloads
NVIDIA CUDA on WSL and AMD equivalents evolve by driver version. For ML, install the Windows driver stack Microsoft documents for WSL GPU support, then follow your framework’s Linux install inside WSL.
Why mention GPU? Many tutorials skip Windows driver prerequisites and blame WSL when nvidia-smi fails in Linux.
Networking and localhost
WSL2 uses a virtual network; localhostForwarding=true in .wslconfig helps Windows apps reach services bound in WSL. If you hit odd firewall issues, test with curl from both sides and temporarily allow the app through Windows Defender Firewall.
Integrate with VS Code and Git on Windows
Install Visual Studio Code on Windows, then add the WSL extension. From a Linux terminal in your project folder, run code . to open the folder against the WSL remote server. Extensions like Python and ESLint should be installed in the WSL context (VS Code prompts you) so binaries resolve to Linux paths.
Git credentials often confuse new setups. Git Credential Manager integrates with Windows auth and works across WSL and native Git for Windows. Inside WSL:
git config --global credential.helper "/mnt/c/Program Files/Git/mingw64/bin/git-credential-manager.exe"
Adjust the path if Git is installed elsewhere. Why? Prevents repeated GitHub HTTPS logins and token paste errors.
systemd and long-running services (newer WSL)
Recent WSL builds support systemd in some distros—enable in /etc/wsl.conf:
[boot]
systemd=true
Then wsl --shutdown and reopen. Why systemd? Some dev stacks (certain databases, enterprise tooling) expect service units—not manual nohup hacks.
Compare WSL2 to a full Hyper-V VM
| Factor | WSL2 | Hyper-V VM |
|---|---|---|
| Boot time | Seconds | Minutes |
| GUI Linux apps | WSLg integrated | Separate display or RDP |
| Kernel | Microsoft-managed utility VM | You manage |
| Best for | Daily dev, Docker Desktop | Isolated networks, Windows Server testing |
Use Hyper-V when you need hard network isolation or to snapshot entire machine states for lab exams. Use WSL2 when you live in VS Code and terminals daily.
Enterprise and compliance notes
Managed PCs may disable optional features via policy. If wsl --install errors with policy text, request Virtual Machine Platform approval from IT rather than fighting MDM with unsupported hacks. Logging and antivirus still apply inside Linux—treat WSL as a development environment on a corporate asset, not a shadow IT escape hatch.
Troubleshooting
| Issue | Fix |
|---|---|
| Virtualization disabled | Enable VT-x/AMD-V in BIOS |
| WSL2 requires update | Run wsl --update; install latest kernel package |
| Distro stuck Installing | wsl --shutdown; reset Microsoft Store components; reinstall distro |
| Docker cannot connect | Confirm WSL integration on; restart Docker after wsl --shutdown |
| Very slow npm/git | Move repo off /mnt/c/ into ~/ |
| 0x80370102 | Enable Virtual Machine Platform; verify hypervisor not blocked by other hypervisors |
Key takeaways
wsl --installis the fastest supported path on Windows 11.- Use WSL2, keep projects in the Linux filesystem, and edit via Remote - WSL.
- Tune RAM and CPU with
.wslconfigwhen running Docker alongside desktop apps. - Docker Desktop + WSL integration is the straightforward container route for most users.
- Export distros before risky experiments;
wsl --updatefixes many kernel issues.
FAQ
Can I run GUI Linux apps? WSLg on Windows 11 supports many GUI apps without extra X servers—update WSL if GUI fails.
Is WSL2 good for production servers? It is a dev tool, not a server replacement—use real Linux VMs or cloud for production.
Hyper-V conflict? WSL2 uses Hyper-V technology; some third-party hypervisors conflict—choose one primary stack or use nested settings documented by your vendor.
