Back to Blog
5 min read

A Step-by-Step Guide to Installing Docker Desktop on Windows 11 using WSL 2

Get Docker Desktop running on Windows 11 with WSL 2. This guide walks you through enabling WSL 2, installing Docker Desktop, and configuring everything step by step. Perfect for developers who want to containerize applications on Windows.

J

Jamie

LogicCore Digital

A Step-by-Step Guide to Installing Docker Desktop on Windows 11 using WSL 2

Docker Desktop on Windows 11 is a game-changer for developers. It packages your applications and all their dependencies into containers - standardized boxes that run consistently everywhere. No more "it works on my machine" headaches. Your app runs the same in development, staging, and production.

When you pair Docker Desktop with Windows Subsystem for Linux 2 (WSL 2), you get the best of both worlds. WSL 2 runs a genuine Linux environment directly on Windows, which makes Docker run faster and more efficiently than older virtualization methods. It's the recommended setup for Docker on Windows 11, and this guide will walk you through getting it configured from scratch.

What You'll Need

Before we start, make sure your system meets these requirements:

  • Windows 11: You need a 64-bit version of Windows 11. Docker Desktop works on Windows 11 Pro, Enterprise, Education, and Home editions. For Home editions, WSL 2 is required (which this guide covers). Build 19044 or newer is recommended.
  • WSL 2 Enabled: The Windows Subsystem for Linux feature must be installed and configured to use version 2.
  • Linux Distribution: You need at least one Linux distribution installed through the Microsoft Store. Ubuntu is a solid, reliable choice that works well for most developers.
  • Hardware Virtualization: Your processor must support virtualization, and it needs to be enabled in your BIOS or UEFI settings. Most modern computers have this enabled by default. If you run into issues later, you might need to restart and access your BIOS/UEFI settings (usually by pressing F2, F10, or Del during startup) to enable options like "Intel VT-x," "AMD-V," or "SVM Mode."
  • Administrator Privileges: You'll need administrator access to enable Windows features and install Docker Desktop.
  • Internet Connection: You'll be downloading Docker Desktop and Linux distributions, so a stable connection is essential.

Step 1: Enable Required Windows Features

If you haven't already enabled WSL and virtualization features, you'll need to do that first. The easiest way is through PowerShell with administrator privileges.

  1. Open PowerShell as Administrator: Click the Start button, type "PowerShell," right-click on "Windows PowerShell," and select "Run as administrator." Confirm any permission prompts.
  2. Enable the Virtual Machine Platform: Copy and paste this command into PowerShell and press Enter:
powershell
dism.exe /online /enable-feature /featurename:VirtualMachinePlatform /all /norestart
  1. Enable Windows Subsystem for Linux: Copy and paste this command into PowerShell, then press Enter:
powershell
dism.exe /online /enable-feature /featurename:Microsoft-Windows-Subsystem-Linux /all /norestart
  1. Restart Your Computer: A system restart is required for these changes to take effect. Restart your computer now before continuing.

Step 2: Install a Linux Distribution

If you don't already have a Linux distribution installed for WSL, you can grab one from the Microsoft Store.

  1. Open Microsoft Store: Find it in your Start menu or search for "Microsoft Store."
  2. Search for Ubuntu: In the search bar, type "Ubuntu" (or another distribution like "Debian" if you prefer). The standard Ubuntu release (often marked LTS for Long-Term Support) is recommended for general use.
  3. Install: Click the "Install" or "Get" button for the distribution you chose.
  4. Launch and Set Up: After installation completes, find Ubuntu (or your chosen distribution) in your Start menu and launch it. The first time it runs, it will perform initial setup, which may take a few minutes. You'll be asked to create a username and password for use within this Linux environment. Choose these carefully and remember them - you'll need them for administrative tasks within WSL.

Step 3: Configure WSL to Use Version 2

It's important to ensure that WSL uses version 2 for optimal performance with Docker. Let's verify and configure this.

  1. Open PowerShell as Administrator (if you closed the previous window).

  2. (Optional) Check Existing WSL Versions: If you previously installed Linux distributions, you can check which WSL version they're using. Run this command:

powershell
wsl --list --verbose

This displays a list of your installed Linux systems and the WSL version (1 or 2) assigned to each. If you have an installation using version 1 that you want to update, use the following command, replacing <DistroName> with the actual name shown in the list (e.g., "Ubuntu"):

powershell
wsl --set-version <DistroName> 2

The conversion process might take several minutes.

  1. Set WSL 2 as Default: Copy and paste this command into PowerShell and press Enter:
powershell
wsl --set-default-version 2

Note: If you receive a message about updating the WSL kernel, run wsl --update in the administrator PowerShell window, wait for it to complete, and then run the wsl --set-default-version 2 command again.

Step 4: Download and Install Docker Desktop

Now you can proceed with installing Docker Desktop itself.

  1. Navigate to Docker Website: Open your web browser and go to the official Docker Desktop download page: https://www.docker.com/products/docker-desktop/
  2. Download Docker Desktop for Windows: Click the button to download the Docker Desktop for Windows installer file.
  3. Run the Installer: Locate the downloaded installer file (usually named Docker Desktop Installer.exe) in your Downloads folder and double-click it to run.
  4. Follow Installation Wizard: During the installation process, make sure the configuration option "Use WSL 2 instead of Hyper-V" is selected (checked). This option is typically enabled automatically if the installer detects a working WSL 2 setup, but it's good practice to verify.
  5. Restart if Required: After installation completes, Docker Desktop may prompt you to log out of Windows and log back in, or to restart your computer. Follow the instructions provided.

Step 5: Configure Docker Desktop Settings for WSL 2

After Docker Desktop is installed (and you've restarted or logged back in if required), it should start automatically. Let's verify and configure the WSL 2 integration.

  1. Locate Docker Icon: Find the Docker icon (a whale symbol) in the Windows system tray, typically near the clock in the bottom-right corner of the screen. If the icon isn't visible, open Docker Desktop from the Start menu.
  2. Open Settings: Right-click on the Docker system tray icon and select Settings.
  3. Verify WSL 2 Engine: In the Settings window, select the General tab from the left-hand menu. Verify that the checkbox labeled "Use the WSL 2 based engine" is selected. If it's not, click the checkbox to enable it, and then click the "Apply & Restart" button.
  4. Configure WSL Integration: Next, select the Resources tab, and then click on WSL Integration.
  5. Enable Integration: Ensure the main toggle switch labeled "Enable integration with my default WSL distro" is turned on.
  6. Enable Specific Distributions: Below this, you'll see a list of the Linux distributions you have installed via WSL (e.g., Ubuntu). To allow Docker commands to be run from within a specific Linux environment, turn the toggle switch on for that distribution. Enable it for the distributions you intend to use with Docker.
  7. Apply Settings: Click the "Apply & Restart" button to save these settings.

Step 6: Verify the Docker Installation

Let's perform a quick check to ensure Docker is installed and running correctly.

  1. Open Windows PowerShell or Windows Terminal: You can use either application.

  2. Check Docker Version: Type the following command and press Enter:

bash
docker --version

The command should output the version numbers for the Docker client and engine.

  1. Run Test Container: Run a standard test container by typing this command and pressing Enter:
bash
docker run hello-world

Docker will download a small test image and run it. If the installation is successful, you'll see a message on your screen that begins with "Hello from Docker!"

  1. (Optional) Verify Integration from within WSL: You can also test Docker from inside your Linux environment. Launch your installed Linux distribution (e.g., Ubuntu) from the Start menu. In the Linux terminal window that appears, type the following commands, pressing Enter after each:
bash
# These commands are run inside the Linux terminal
docker --version
docker run hello-world

If these commands execute successfully and show the version or the "Hello from Docker!" message, the integration with WSL 2 is working correctly.

Troubleshooting Common Issues

If you encounter problems, here are some common issues and solutions:

  • Docker Doesn't Start: Ensure you granted the necessary permissions during installation. Try restarting Docker Desktop from the Start menu or via the system tray icon. Check that WSL 2 is properly configured and that your Linux distribution is running.
  • WSL 2 Not Detected: If Docker Desktop doesn't detect WSL 2, verify that WSL 2 is set as the default version using wsl --set-default-version 2. Also check that you have at least one Linux distribution installed and that it's using WSL 2 (verify with wsl --list --verbose).
  • Permission Errors: Running Docker commands might sometimes require specific user permissions. Ensure your user account has the necessary rights, and that you've enabled WSL integration for your specific Linux distribution in Docker Desktop settings.
  • Virtualization Issues: If you're getting errors related to virtualization, check that hardware virtualization is enabled in your BIOS/UEFI settings. You may need to restart your computer and access these settings during startup (usually F2, F10, or Del keys).
  • WSL Kernel Update Required: If you see messages about the WSL kernel, run wsl --update in an administrator PowerShell window and restart your computer.
  • Check System Requirements: Double-check that your Windows 11 version and hardware meet the minimum requirements for Docker Desktop and WSL 2.

You're All Set

That's it! You've got Docker Desktop installed and running on your Windows 11 system with WSL 2 integration. You now have both the powerful Docker Engine for command-line work and the Desktop GUI for visual management. You can run Docker commands from both Windows PowerShell and your WSL Linux distributions. You're ready to start building, running, and managing containers.

Helpful Resources

Want to dive deeper? These official resources are worth bookmarking:

Published on April 20, 2025