Set Up a Modern Local Dev Environment with WSL2, VS Code & Docker on Windows 10/11

Set Up a Modern Local Dev Environment with WSL2, VS Code & Docker on Windows 10/11​

Difficulty: Intermediate | Time Required: 30-45 minutes

Introduction​

Developing on Windows used to mean tradeoffs: poor POSIX compatibility, slow filesystem IO in cross-platform toolchains, or switching to a VM. WSL2 (Windows Subsystem for Linux 2) changes that: it gives you a genuine Linux kernel with excellent performance, works seamlessly with Docker Desktop, and integrates tightly with Visual Studio Code. This tutorial walks you through setting up WSL2, VS Code (with Remote - WSL), and Docker Desktop so you can run containers and develop as if you were on Linux — all from Windows 10/11.

Prerequisites​

• Windows 10 version 2004 (build 19041) or later is recommended for smooth WSL2 experience. Windows 11 is fully supported.
  • Check your version: press Win+R, type winver, press Enter.
• 64-bit system with virtualization enabled in BIOS/UEFI.
• Administrative privileges to enable Windows features and install programs.
• Internet connection to download packages and images.

Detailed step-by-step instructions​

1. Verify Windows version and virtualization
   1. Press Win+R → type winver → Enter to confirm OS version.
   2. Ensure virtualization is enabled in BIOS/UEFI (look for Intel VT-x, AMD-V). You can check in Task Manager → Performance → CPU (it will show "Virtualization: Enabled").
2. Enable WSL and Virtual Machine Platform
   • Modern method (Windows 10 2004+ and Windows 11):
     1. Open an elevated PowerShell (right-click → Run as administrator).
     2. Run:
        wsl --install
        This will enable required features, install WSL2 and a default Ubuntu distro, and reboot if needed.
   • Manual method (if wsl --install not available):
     1. In elevated PowerShell:
        

        dism.exe /online /enable-feature /featurename:Microsoft-Windows-Subsystem-Linux /all /norestart
        dism.exe /online /enable-feature /featurename:VirtualMachinePlatform /all /norestart

     2. Restart your PC.
     3. After reboot, set WSL2 as default:
        wsl --set-default-version 2
     4. If prompted about a Linux kernel update, download and install the WSL2 Linux kernel update package from Microsoft (link shown in the message) and re-run the command.
3. Install a Linux distribution
   1. Open the Microsoft Store and install "Ubuntu" (or your preferred distro like Debian, Kali, Fedora WSL).
   2. Launch the distro (from Start menu), create a UNIX username and password.
   3. Verify WSL version:
      wsl -l -v
      Ensure your distro is using version 2. If not:
      wsl --set-version <DistroName> 2
4. Install Visual Studio Code and the Remote - WSL extension
   1. Download and install VS Code from Visual Studio Code - Code Editing. Redefined.
   2. Open VS Code → Extensions (left bar) → Search for "Remote - WSL" → Install.
   3. Tip: also install helpful dev extensions like "Docker", "Prettier", language-specific extensions.
5. Install Docker Desktop and enable WSL2 integration
   1. Download Docker Desktop from Get Started | Docker and run the installer.
   2. During installation, choose "Use WSL 2 instead of Hyper-V" (or enable WSL 2 backend in settings later).
   3. After install, open Docker Desktop → Settings → Resources → WSL Integration → enable integration for your distro(s).
   4. In a WSL terminal (Ubuntu), test Docker:
      

      docker run --rm hello-world
      docker version
      docker info

      If the command runs and prints the hello-world message, Docker is working inside WSL.
6. Start a project inside the WSL filesystem and open it with VS Code
   1. From your WSL shell:
      

      mkdir -p ~/projects/myapp
      cd ~/projects/myapp
      git clone <your-repo-url> .   # or start a new project
      code .

      The code . command opens the folder in VS Code using the Remote - WSL connection.
   2. Use the integrated terminal (which will be your WSL shell) and run Docker Compose or build commands as usual.

Tips, warnings, and troubleshooting notes​

• Tip: Keep project files inside the Linux filesystem (e.g., /home/username/projects) for best performance. Accessing Windows files from WSL (like /mnt/c/) is slower.
• Tip: If you have existing Hyper-V VMs or third-party virtualization tools (VirtualBox older versions), ensure they are compatible. Most modern VirtualBox releases support Hyper-V; otherwise, conflicts may appear.
• Warning: If you get "WslRegisterDistribution failed" or kernel errors, install/repair the WSL2 kernel package from Microsoft and run wsl --update.
• Troubleshooting Docker:
  • If Docker commands fail inside WSL, open Docker Desktop → Settings → General → ensure "Use the WSL 2 based engine" is selected.
  • Check integration: Docker Desktop → Resources → WSL INTEGRATION → selected distros.
  • Run wsl --shutdown to restart WSL and then relaunch your distro.
• Common commands:
  • Update WSL: wsl --update
  • Show status: wsl --status
  • Convert a distro: wsl --set-version Ubuntu 2
• Networking note: WSL2 uses virtualized networking. Most dev workflows (web servers, containers) work without changes, but if you need to expose services to the host, bind to 0.0.0.0 or use localhost mapping in Docker Desktop.
• VS Code tip: If you see slow extension installs or connections, open the VS Code command palette (Ctrl+Shift+P) and choose "Remote-WSL: New Window" to force a clean WSL window.

Conclusion​

In ~30–45 minutes you can transform your Windows machine into a modern, Linux-friendly developer workstation. WSL2 gives you a real Linux kernel and fast I/O; VS Code Remote - WSL provides a first-class editing experience with extensions and debugging; Docker Desktop's WSL2 backend enables containerized workflows without heavy VMs. This stack is ideal for web developers, backend engineers, and anyone who benefits from Linux tools while staying on Windows.
Key Takeaways:

• WSL2 provides a full Linux kernel and fast filesystem performance on Windows 10 (2004+) and Windows 11.
• VS Code Remote - WSL allows seamless development inside the Linux environment with familiar Windows tooling.
• Docker Desktop integrates with WSL2, making container workflows simple and native.
• Keep project files in the WSL filesystem for best speed and use wsl --update / wsl --status for diagnostics.

---

This tutorial was generated to help WindowsForum.com users get the most out of their Windows experience.