sodcalculator

10 Tech How-To

Run Linux Containers in WSL with Docker Desktop

Guide 10-21235 · Updated · Step by step

This guide shows you how to run Linux containers in Windows Subsystem for Linux (WSL) using Docker Desktop. You’ll set up WSL 2, install Docker Desktop, and run your first container—all from the Windows command line or PowerShell. By the end, you’ll have a working Docker environment that uses WSL 2’s lightweight virtual machine for better performance and compatibility.

What You’ll Need

  • Windows 10 version 2004 or higher, or Windows 11 (any edition).
  • Administrator access to your PC (to install WSL and Docker Desktop).
  • At least 4 GB of RAM (8 GB recommended) and enough free disk space (about 10 GB for the WSL virtual disk).
  • A stable internet connection to download the required components.

Step-by-Step

  1. Enable WSL 2. Open PowerShell or Windows Terminal as Administrator. Run: wsl --install. This installs the WSL 2 kernel and sets it as the default. If you already have WSL 1, upgrade your existing distro with wsl --set-version <distro-name> 2 (replace with your distro name, e.g., Ubuntu).
  2. Restart your PC when prompted. WSL 2 requires a reboot to activate the virtualization components.
  3. Install a Linux distribution (if not already installed). Open the Microsoft Store, search for “Ubuntu” (or any distro you prefer), and click “Get”. After installation, launch it once to finish setup—create a username and password. You can also install a distro from the command line with wsl --install -d Ubuntu.
  4. Download Docker Desktop. Go to the official Docker website and download the Docker Desktop for Windows installer. Run the installer.
  5. Select WSL 2 backend. During installation, ensure the checkbox “Use WSL 2 instead of Hyper-V” is checked. If you missed it, you can change it later in Docker Desktop’s settings under “General”.
  6. Complete the installation and restart your computer if asked. After restart, Docker Desktop will start automatically. If not, launch it from the Start menu.
  7. Enable WSL integration. Click the Docker Desktop icon in the system tray, go to “Settings” → “Resources” → “WSL Integration”. Toggle on “Enable integration with my default WSL distro” and select the distro you installed (e.g., Ubuntu). Click “Apply & Restart”.
  8. Verify the installation. Open a terminal (PowerShell, CMD, or your WSL distro) and run: docker --version. You should see the Docker version. Then run docker run hello-world. This pulls a small test image and runs it. If you see the “Hello from Docker!” message, everything works.
  9. Run a Linux container. Now you can run any Linux container. For example, docker run -it ubuntu bash starts an interactive Ubuntu container. You’ll be inside a Bash shell in a Linux environment—even though your host is Windows.
  10. Stop and remove containers when done. Use docker ps to list running containers, docker stop <container-id> to stop one, and docker rm <container-id> to remove it.

Common Mistakes

  • Forgetting to enable WSL 2 before installing Docker Desktop. Docker Desktop can fall back to Hyper-V, but WSL 2 gives better performance and integration.
  • Not restarting after WSL installation. WSL 2 won’t work until you reboot. If you skip this, Docker Desktop may fail to start.
  • Using the wrong terminal. Docker commands work in PowerShell or CMD, but if you want to run Linux commands inside a container, you need to be in your WSL distro’s terminal or use wsl from PowerShell.
  • Leaving WSL integration off. If you don’t enable integration, Docker Desktop will still work but only from PowerShell/CMD, not from inside your WSL distro. This can confuse users who expect to run docker in Ubuntu.
  • Running out of disk space. WSL 2 creates a virtual hard disk (VHDX) that grows over time. If you pull many large images, it can fill up your drive. Monitor your disk usage.

Tips

  • Use WSL 2 for better performance. File I/O is faster than WSL 1, and Docker containers run with near-native speed.
  • Set a default distro. If you have multiple distros, set one as default with wsl --set-default <distro-name> so Docker Desktop knows which one to integrate with.
  • Keep Docker Desktop updated. Enable automatic updates in Docker Desktop settings to get the latest features and security fixes.
  • Use Docker contexts. You can switch between WSL 2 and other Docker environments with docker context use desktop-linux (the default for WSL 2).
  • Store images on a different drive. If your C: drive is small, you can move the WSL virtual disk to another drive using wsl --export and wsl --import.

Troubleshooting

  • Docker Desktop fails to start. Make sure WSL 2 is properly installed: run wsl --status in PowerShell. If it says “Default Version: 2”, you’re good. If not, run wsl --set-default-version 2. Also, check that virtualization is enabled in your BIOS (look for “Intel VT-x” or “AMD-V”).
  • “WSL 2 requires an update” error. Download and install the latest WSL 2 kernel update from the Microsoft website, then restart.
  • Docker commands not found in WSL distro. This usually means WSL integration is off. Go to Docker Desktop settings → Resources → WSL Integration, enable it, and restart Docker Desktop.
  • Container runs but no network. Try restarting Docker Desktop. If that fails, reset the WSL network with wsl --shutdown and then start Docker Desktop again.
  • Out of memory errors. Increase the memory limit for WSL 2 by creating a .wslconfig file in your user folder (e.g., C:\Users\YourName\.wslconfig) with [wsl2] and memory=6GB (adjust as needed). Then restart WSL with wsl --shutdown.
  • Docker Desktop shows “Docker Engine stopped”. Sometimes the engine fails to start due to a corrupted state. Try “Restart” from the Docker Desktop menu. If that doesn’t work, run wsl --shutdown and start Docker Desktop again.

Frequently Asked Questions

Can I run Linux containers without Docker Desktop?

Yes, you can install Docker Engine directly inside your WSL distro, but that requires manual setup and maintenance. Docker Desktop simplifies the process and adds a GUI, automatic updates, and easy integration.

Do I need to use a specific Linux distro?

No, Docker Desktop works with any WSL 2 distro. Ubuntu is the most common, but you can use Debian, Alpine, Kali, or others. The integration settings let you choose which distro Docker commands are available in.

Can I run Windows containers with Docker Desktop?

Yes, but not simultaneously with Linux containers. You can switch between Linux and Windows containers by right-clicking the Docker Desktop icon and selecting “Switch to Windows containers”. Note that Windows containers require Windows Server Core or similar images and are not as common for development.

Will Docker Desktop slow down my PC?

Docker Desktop runs a lightweight VM (via WSL 2) that uses some RAM and CPU. It only consumes resources when Docker is running. You can stop Docker Desktop when not in use to free up memory.

How do I update Docker Desktop?

Docker Desktop checks for updates automatically and notifies you. You can also go to the Docker Desktop menu (the whale icon) → “Check for Updates”. Updates install over the existing version without losing your containers or images.

Can I use Docker commands from PowerShell even if I don’t use WSL?

Yes, Docker Desktop works from PowerShell or CMD regardless of WSL integration. However, using WSL 2 gives you a more seamless Linux experience, especially for mounting files and running Linux-specific tools.

Related

General steps for current mainstream versions; menus can differ by device and version. See the disclaimer or report an error.

More in this bed

The whole Tech How-To bed →