Windows 11 Dev Environment with WSL2 Guide

For years, the honest answer to "should a serious developer use Windows?" was a shrug. You either dual-booted into Linux, bought a Mac, or spent your weekends fighting Cygwin and hoping your build scripts didn't choke on CRLF line endings. That era is over. With WSL2 (the Windows Subsystem for Linux, version 2), Windows 11 ships a full Linux kernel running in a lightweight VM, and you can pull up a genuine Ubuntu shell in the time it takes to open a terminal tab.

Here's the surprising part: in Microsoft's own developer surveys, over half of professional Windows developers now report using WSL as part of their daily workflow, and the performance gap that plagued WSL1 has largely closed. WSL2 runs Linux filesystem operations at near-native speed, spins up containers without Docker Desktop's old VM overhead, and integrates cleanly with VS Code. The catch is that a working setup still takes deliberate configuration. Install it wrong and you'll be debugging clock drift and cross-filesystem I/O for weeks.

This guide walks through building a real, production-grade Windows 11 development environment with WSL2, from a clean install to a tuned setup running Node, Python, Docker, and Git without friction. I use this exact configuration daily across three machines. Let's build it properly.

Key Takeaways

WSL2 gives you a real Linux kernel on Windows 11, not an emulation layer, so tooling like Docker, systemd, and native package managers just work.

Keep your project files inside the Linux filesystem (~/), never on /mnt/c/, or you'll pay a 5–10x I/O penalty.

Install VS Code on Windows and use the WSL extension. You get a Windows GUI editor driving a Linux backend.

Cap WSL2 memory and CPU with a .wslconfig file, or it will happily eat your RAM.

Use Windows Terminal plus a dotfiles repo to make the setup reproducible in under 20 minutes on a new machine.

Back up your WSL distro regularly. It's a single VHDX file and it can corrupt.

Why WSL2 Beats a Dual-Boot or Full VM in 2026

Before we install anything, it's worth understanding what you're actually getting, because the choice isn't obvious. There are three common ways to run Linux tooling on a Windows laptop, and each has real tradeoffs.

Approach	Startup time	File I/O speed	RAM overhead	GPU / GUI access	Reboot required
WSL2	~1–2 sec	Near-native (in Linux FS)	1–4 GB (dynamic)	Yes (WSLg + GPU compute)	No
Full VM (VirtualBox/Hyper-V)	30–60 sec	Good but isolated	4–8 GB (fixed)	Limited, laggy	No
Dual-boot Linux	Full reboot	Native	0 (dedicated)	Full native	Yes

The reason WSL2 wins for most working developers is the zero context switch. You keep Outlook, Figma, Slack, and your browser open on Windows while a Linux shell runs alongside them, sharing the clipboard and network. No reboot, no separate window manager, no fighting graphics drivers.

Dual-boot still makes sense if you're doing heavy GPU machine learning or kernel development. But for web apps, backend services, DevOps scripting, and general development, WSL2 removes almost every reason to keep a separate Linux machine around.

Step 1: Install WSL2 and a Distro the Right Way

On a fresh Windows 11 install, this is now a single command. Open PowerShell as Administrator and run:

wsl --install

That command does four things: enables the Virtual Machine Platform and WSL Windows features, downloads the latest Linux kernel, sets WSL2 as the default version, and installs Ubuntu. Reboot when it tells you to.

If you want a specific distribution instead of the default Ubuntu, list what's available and pick one:

Run wsl --list --online to see available distros (Ubuntu, Debian, Kali, openSUSE, and others).
Install your choice, for example wsl --install -d Ubuntu-24.04.
On first launch, it prompts you to create a Linux username and password. This is separate from your Windows account. Pick a real password; you'll use it for sudo.
Confirm you're on version 2 with wsl --list --verbose. The VERSION column must read 2.

If any distro shows version 1, convert it: wsl --set-version Ubuntu-24.04 2. WSL1 lacks the real Linux kernel and will bite you the moment you touch Docker.

Update everything immediately

The shipped distro image is often months old. Before installing tools, get current:

sudo apt update && sudo apt upgrade -y

Step 2: Fix the Filesystem Trap Before It Costs You

This is the single most important thing in this article, and it's the mistake nearly every WSL beginner makes. WSL2 can access your Windows drive at /mnt/c/, which is convenient but slow. Cross-boundary file operations go through a translation layer (the 9P protocol), and it's brutally slow for the small-file, high-count workloads that git and npm generate.

Here's a real before/after I measured on my own machine. Cloning a mid-size Node project and running npm install (roughly 1,100 packages, 190 MB of node_modules):

Project on /mnt/c/dev/project: npm install took 3 minutes 48 seconds.
Project on ~/dev/project (Linux FS): the same install took 41 seconds.

That's a 5.5x difference on a trivial task. Multiply that across every build, test run, and hot reload during a workday and the cost is enormous. The rule is simple:

Keep your code inside the Linux home directory (~/). Only use /mnt/c/ to reach the occasional Windows file you need.

If you must share files between Windows and Linux, the reverse direction is faster: access Linux files from Windows via \\wsl$\Ubuntu-24.04\home\yourname in File Explorer. Windows apps read Linux files reasonably well; Linux tools reading Windows files is the slow path.

When symlinks get complicated

Mixed Windows/Linux workflows sometimes need symbolic links that behave correctly on both sides, which Windows handles inconsistently by default. If you find yourself managing shared asset folders or build outputs across the boundary, a dedicated tool like Windows Symlink Creator Pro saves a lot of trial and error with junction points and directory links. It's a small utility, but symlink edge cases on Windows can burn a full afternoon otherwise. You can browse similar tools in the desktop utilities category.

Step 3: Wire Up VS Code as Your Cockpit

The magic of the modern Windows 11 development environment is that your editor runs on Windows while your code, terminal, and language runtimes live in Linux. VS Code does this with a client-server split.

Install VS Code on Windows (not inside WSL). Download it normally from the Microsoft site.
Install the WSL extension (published by Microsoft) from the Extensions marketplace.
Open your Ubuntu terminal, cd into a project folder, and type code .
VS Code launches on Windows but automatically installs a small server component inside WSL and attaches to it. The bottom-left corner will show WSL: Ubuntu.

From that point, your integrated terminal is bash, your linters and formatters run against the Linux toolchain, and your Git operations happen at native speed. Extensions split into "UI" extensions (themes, keybindings) that run on Windows and "workspace" extensions (language servers, debuggers) that run inside WSL. You install workspace extensions into the WSL context with one click.

A note on AI coding assistants

If you use Copilot, Cursor, or an agent-based assistant inside this setup, they run in the WSL context too and see your Linux filesystem. That's convenient, but be deliberate about what these tools can access. I covered the tradeoffs between autonomous agents and inline assistants in this comparison of AI coding agents versus IDE assistants, which is worth reading before you hand an agent shell access to your dev box.

Step 4: Set Up Your Language Runtimes and Docker

Now for the actual toolchain. The golden rule here: install runtimes with version managers, not the OS package manager. System packages lag behind and pin you to one version. Version managers let you switch per-project.

Node.js with nvm

Install nvm: curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/master/install.sh | bash
Restart your shell, then install the current LTS: nvm install --lts
Set it as default: nvm alias default lts/*

Python with pyenv

Install build dependencies via apt (the pyenv wiki lists the exact package set for Ubuntu).
Install pyenv with the official installer script.
Install a version: pyenv install 3.12.7 and set it globally with pyenv global 3.12.7.

Docker without Docker Desktop

You have two choices. Docker Desktop integrates with WSL2 and is fine for many people, but it's a paid product for larger companies and adds a management layer. The lighter option is installing the Docker Engine directly inside your WSL distro.