Fixing Docker Desktop's WSL2 Backend Integration Issues
Docker Desktop configured to use the WSL2 backend suddenly can't see your distro, or containers fail to start with confusing errors. Here's how to work through the specific integration points that commonly break.
Docker Desktop’s WSL2 backend integrates two separately-updating systems — Docker Desktop itself and your WSL2 distros — and integration issues between them are common enough to be worth a dedicated, systematic troubleshooting path.
Step 1: confirm Docker Desktop is actually configured for the WSL2 backend
Docker Desktop → Settings → General →
confirm "Use the WSL 2 based engine" is checkedDocker Desktop can run on an older Hyper-V-based backend instead — confirming WSL2 backend mode is actually enabled is the necessary first check before troubleshooting WSL2-specific integration issues.
Step 2: confirm your specific distro has WSL integration enabled
Docker Desktop → Settings → Resources → WSL Integration →
confirm the toggle is enabled for your specific distroDocker Desktop’s WSL2 integration must be explicitly enabled per-distro — a distro installed after Docker Desktop’s own setup, or a newly created distro, often needs this toggle enabled manually before docker commands work inside it at all.
Step 3: check the docker command actually resolves inside the distro
which docker
docker versionIf docker isn’t found at all inside your distro despite integration appearing enabled, the integration may need to be toggled off and back on to force Docker Desktop to re-inject its CLI tooling into that specific distro.
Step 4: restart Docker Desktop itself, not just the distro
Docker Desktop maintains its own connection state to each integrated WSL2 distro — restarting Docker Desktop directly (not just running wsl --shutdown) often resolves stale-connection issues that a distro-only restart won’t fix, since Docker Desktop’s own state also needs to reinitialize.
Step 5: check for a WSL2 version mismatch after a WSL update
wsl --versionA significant WSL platform update sometimes outpaces Docker Desktop’s own tested compatibility — checking Docker Desktop’s release notes for known compatibility issues with your specific current WSL version is worth doing if integration broke immediately following a WSL update.
Step 6: check for a resource conflict via .wslconfig
If Docker Desktop’s containers are failing due to resource exhaustion rather than a connection failure specifically, check whether a memory ceiling set in .wslconfig is too restrictive for both your regular WSL usage and Docker’s containers running simultaneously — both draw from the same overall WSL2 VM resource pool.
Step 7: check for the Docker daemon failing to start inside the distro
sudo service docker statusIf Docker Desktop’s own WSL2 integration appears healthy but containers still won’t run, confirm the actual Docker daemon process is running inside the distro — a stopped or crashed daemon inside the distro is a distinct problem from the Docker Desktop-to-WSL2 integration layer itself.
Step 8: fully reset Docker Desktop’s WSL integration as a last resort
Docker Desktop → Settings → Resources → WSL Integration →
disable for all distros → apply → re-enable →
apply againToggling integration off and back on forces Docker Desktop to fully re-establish its connection to each distro from a clean state, resolving integration issues that persist through simple restarts.
Why this integration has more moving parts than it first appears
Docker Desktop’s WSL2 backend genuinely spans two independently-updating systems — Docker Desktop’s own release cycle and WSL2’s own update cycle, now decoupled from Windows itself since WSL’s move to standalone Store distribution — meaning integration issues can originate from either side changing independently, which is exactly why a systematic check of both halves separately resolves these issues faster than assuming the fault lies with whichever side you happen to have updated most recently.