# How to Set Up Windows Subsystem for Linux (WSL2) with Docker Desktop
For developers working on a Windows machine, running Linux-based applications, scripts, and containers used to require cumbersome dual-boot setups or resource-heavy virtual machines. The introduction of the Windows Subsystem for Linux (WSL), specifically WSL2, fundamentally changed this by allowing a full Linux kernel to run seamlessly alongside Windows.
When combined with Docker Desktop, WSL2 provides an incredibly powerful, fast, and native-feeling development environment for building and testing containerized applications.
This guide details the complete workflow for installing WSL2, configuring a Linux distribution, and integrating it flawlessly with Docker Desktop on Windows 10 or Windows 11.
## Step 1: Install Windows Subsystem for Linux (WSL2)
Microsoft has drastically simplified the installation process for WSL in recent versions of Windows.
1. Open **PowerShell** or **Windows Terminal** as an Administrator. (Right-click the Start button and select “Windows Terminal (Admin)” or “Windows PowerShell (Admin)”).
2. Execute the following command:
“`powershell
wsl –install
“`
This single command performs several actions:
– It enables the required optional Windows features (Virtual Machine Platform and Windows Subsystem for Linux).
– It downloads and installs the latest Linux kernel.
– It sets WSL2 as the default version.
– It downloads and installs the default Linux distribution, which is Ubuntu.
*Note: If you already have WSL installed and want to ensure you are using WSL2, run `wsl –set-default-version 2`.*
3. **Restart your computer.** A reboot is strictly required to apply the Virtual Machine Platform changes.
## Step 2: Configure Your Linux Distribution
After your PC restarts, a terminal window should automatically open to finalize the Ubuntu installation. If it does not, open the Start menu, search for “Ubuntu,” and launch it.
1. The system will extract the files. This may take a few minutes.
2. You will be prompted to create a **UNIX username**. This does not need to match your Windows username.
3. You will be prompted to create and confirm a **password**. Note that as you type the password, nothing will appear on the screen—this is standard Linux security behavior.
You now have a fully functional Ubuntu Linux environment running inside Windows. You can access it anytime by opening Windows Terminal and selecting the Ubuntu profile, or by typing `wsl` in Command Prompt.
Before proceeding, it is good practice to update your new Linux distribution:
“`bash
sudo apt update && sudo apt upgrade -y
“`
## Step 3: Install Docker Desktop for Windows
With WSL2 running, you can now install Docker Desktop. Docker Desktop will use the WSL2 engine rather than a traditional Hyper-V virtual machine, resulting in significantly faster startup times and better file system performance.
1. Navigate to the official Docker website and download **Docker Desktop for Windows**.
2. Run the installer executable.
3. During the installation, ensure the option **”Use WSL 2 instead of Hyper-V”** is checked. This is critical for the integration to work correctly.
4. Follow the prompts to complete the installation.
5. Once installed, launch Docker Desktop from the Start menu.
6. Accept the terms of service. You may be prompted to log in to Docker Hub, but this is optional for local development.
## Step 4: Verify the WSL2 and Docker Integration
Docker Desktop should now be running in your system tray. The final step is to ensure Docker is properly integrated with your Ubuntu WSL2 instance.
1. Open the Docker Desktop dashboard.
2. Click the **Settings** icon (the gear) in the top right corner.
3. Navigate to **Resources** > **WSL Integration** on the left sidebar.
4. Ensure the checkbox for **”Enable integration with my default WSL distro”** is checked.
5. If you have multiple Linux distributions installed, you can toggle integration for specific distros using the toggle switches below. Ensure the switch next to **Ubuntu** is turned on.
6. Click **Apply & restart** at the bottom right.
## Step 5: Test Your Docker Environment
To confirm that everything is working perfectly, you should be able to run Docker commands directly from within your Linux terminal.
1. Open your **Ubuntu** terminal.
2. Verify the Docker installation by checking the version:
“`bash
docker –version
“`
*You should see output similar to `Docker version 24.0.5, build ced0996`.*
3. Run a test container to ensure the engine is fully operational. We will use the standard `hello-world` image.
“`bash
docker run hello-world
“`
If the integration is successful, Docker will pull the image from Docker Hub, run it, and display a message stating: *”Hello from Docker! This message shows that your installation appears to be working correctly.”*
## Understanding the File System Performance
When working with WSL2 and Docker, file system placement is crucial for performance.
WSL2 provides access to your Windows files (via `/mnt/c/`), and Windows provides access to your Linux files (via `\\wsl$\Ubuntu\`). However, accessing files *across* this boundary is very slow.
**Best Practice:** When developing applications, clone your Git repositories and store your project files **inside the Linux file system** (e.g., `~/, or /home/username/projects/`), not on the Windows `C:` drive.
Docker Desktop running on WSL2 is optimized to read files from the Linux file system. Storing your source code in Linux and opening it in Windows using VS Code’s “Remote – WSL” extension will give you native Linux performance speeds for building and running your Docker containers.