How to Fix Docker Desktop WSL Integration Issues

In this tutorial, you'll learn about How to Fix Docker Desktop WSL Integration Issues. We cover key concepts, practical examples, and best practices.

The Problem

Docker Desktop cannot connect to your WSL 2 Linux distribution, showing Docker Desktop - WSL integration failed or Cannot connect to the Docker daemon when running docker ps inside WSL.

Quick Fix

Enable WSL 2 Backend in Docker Desktop

# In Docker Desktop: Settings > General > Use WSL 2 based engine
echo "Ensure 'Use WSL 2 based engine' checkbox is selected"

Docker Desktop uses the Hyper-V backend by default on Windows. Switch to WSL 2 for better performance and integration with Linux distros.

Enable Integration for Specific WSL Distros

# In Docker Desktop: Settings > Resources > WSL Integration
echo "Select your Ubuntu distro under 'Enable integration with my default WSL distro'"
# Alternatively, from PowerShell run:
wsl --set-version Ubuntu 2
# Conversion in progress, this may take a few minutes...

Enable WSL integration for each distro individually in Docker Desktop settings. The distro must already be running WSL 2 (check with wsl --status).

Set Docker Context Inside WSL

docker context ls
# NAME        TYPE    DESCRIPTION
# default     moby    Current DOCKER_HOST based configuration
docker context use default
# default

Inside WSL, docker commands need to use the default context that connects to Docker Desktop's daemon. Run docker context use default if the context is misconfigured.

Verify Docker Works Inside WSL

docker run hello-world
# Hello from Docker!
# This message shows that your installation appears to be working correctly.
docker ps
# CONTAINER ID   IMAGE     COMMAND   CREATED   STATUS    PORTS     NAMES

Run docker run hello-world to confirm the integration is working. If it hangs, restart Docker Desktop and the WSL distro.

Reset Docker Desktop and WSL When Integration Breaks

wsl --shutdown
# Then restart Docker Desktop manually
docker run hello-world
# Hello from Docker!

Sometimes the WSL integration stops working after a Windows update or Docker Desktop upgrade. Shutting down WSL completely and restarting Docker Desktop clears any stale state and re-establishes the integration.

Inspect Container Configuration

docker inspect <container-id> --format '{{json .Config}}' | python3 -m json.tool
# {
#   "Hostname": "abc123",
#   "Env": ["PATH=/usr/local/bin:..."],
#   "Cmd": ["node", "app.js"]
# }

Use docker inspect to examine the full configuration of a container. This reveals misconfigurations in environment variables, command arguments, and network settings that may not appear in logs.

Additional Troubleshooting

# Check the error message and stack trace for more context
echo "Review the full error output to identify the root cause"

If the above steps do not resolve the issue, examine the complete error message and stack trace. Often the key detail is in the middle of the traceback rather than the final line. Search for the error message in the project documentation or issue tracker for additional solutions.

Prevention

• Keep Docker Desktop and WSL 2 up to date (Docker Desktop auto-updates)
• Use a single primary WSL distro for all Docker work to avoid context confusion
• Restart WSL with wsl --shutdown and Docker Desktop together when integration breaks
• Store Docker projects inside the WSL filesystem (\\wsl.localhost\) for faster I/O