If docker works in a Windows terminal but Ubuntu reports command not found, that distribution probably does not have Docker Desktop’s WSL integration enabled. If the command exists but returns Cannot connect to the Docker daemon, first check whether Docker Desktop is running, which Docker context is active, and whether DOCKER_HOST is set. Identify the failing layer with read-only commands before following the matching steps. Do not start by resetting Docker data or unregistering a WSL distribution.
This guide covers Docker Desktop, WSL 2 Linux distributions, and Linux container workflows on Windows. Docker Desktop’s WSL 2 backend, Docker VMM, and Hyper-V behave differently, so confirm which one you use. Windows container mode is also different from the Linux container environment covered here.
Identify whether Windows, WSL, or the Docker Engine is failing
Collect the basic state in Windows PowerShell:
|
|
These commands do not modify containers or distributions. wsl --list --verbose shows whether each distribution uses WSL 1 or WSL 2. docker version has separate Client and Server sections. If you see only Client and no Server, the CLI was found but did not connect to the Engine.
Then open the Linux distribution you use for development and check it there:
|
|
Compare the two sets of results. This prevents you from confusing “Windows cannot find the program,” “the distribution has no injected CLI,” and “the Engine is not responding.”
Confirm that WSL itself works
If wsl --status, wsl -l -v, or Ubuntu startup fails, troubleshoot WSL and Windows virtualization first. Do not change Docker Desktop settings yet.
Docker currently lists WSL 2.1.5 as the minimum for the Docker Desktop WSL 2 backend and recommends keeping WSL up to date. Check your installed version:
|
|
If WSL is outdated, save any files you are editing, then update and restart the WSL virtual machine:
|
|
wsl --shutdown immediately stops every running WSL distribution. Start Ubuntu again and check wsl -l -v; the target distribution should show 2 in the VERSION column. If it shows 1, do not convert it without backing up important files. Conversion takes time and can fail.
If the WSL update fails, check Microsoft Store, Windows Update, and network policies. wsl --update --web-download switches to a web download path. Do not force Windows to shut down during an update, and do not treat wsl --unregister as a normal restart command.
Make sure Docker Desktop is running in Linux container mode
Confirm in the Windows taskbar that Docker Desktop has finished starting. If its status remains Starting or Docker Engine is starting, or it shows an Engine error, record the full message. A tray menu item named “Switch to Linux containers” may indicate Windows container mode. WSL Linux container development requires Linux containers.
The WSL integration option appears only with a compatible backend and container mode. When Docker Desktop uses the WSL 2 engine, open Settings > General and check “Use the WSL 2 based engine.” Then go to Settings > Resources > WSL Integration, enable the distributions you need, and select Apply.
If you have multiple distributions, the default one may not be the one you opened. Run wsl -l -v, find the exact name, and enable that distribution in the integration page. To change the default distribution:
|
|
Replace Ubuntu with the exact name shown in the list. Changing the default affects WSL commands that do not specify a distribution. It does not convert other distributions to WSL 2 or move their files.
WSL reports that the docker command is missing
If docker version works in Windows PowerShell but the Linux distribution returns command not found, check these items in order:
- Confirm that the target distribution is version 2 in
wsl -l -v. - Enable the WSL 2 engine in Docker Desktop settings.
- Enable the current distribution under Settings > Resources > WSL Integration.
- Select Apply and wait for Docker Desktop to finish applying the change.
- Run
wsl --shutdownin Windows, then reopen the distribution. - Run
command -v dockeranddocker versioninside the distribution.
Do not install another Docker Engine inside the distribution just because the command is missing. Docker warns that installing Docker Engine or the Docker CLI directly in a WSL distribution can conflict with Docker Desktop integration. Having two installations can also make the CLI point at a different daemon, so the container list in Ubuntu does not match Windows.
Running an independent Engine inside Linux is a different deployment choice. Decide explicitly who manages the daemon, data directory, startup service, and Docker context. Do not let two Engines compete for the same development commands.
The command exists, but cannot connect to the Docker daemon
Check that Docker Desktop has fully started in Windows, then run:
|
|
If the current context points to a remote host over SSH or another endpoint, docker may not be using local Desktop. After confirming that, switch to the Desktop context. Do not overwrite Docker configuration blindly; a remote context may be intentional.
In WSL, check whether environment variables override the connection address:
|
|
DOCKER_HOST can force the CLI to use a specific socket or TCP address. DOCKER_CONTEXT can select another context. Record the values and where they came from before removing them from the current terminal temporarily. In PowerShell, inspect:
|
|
Do not treat sudo docker as a general fix. It may use the root user’s configuration and connect to another daemon. For a permissions error, first identify which Docker CLI and Engine are involved.
If Docker Desktop is still starting, retrying Compose commands only repeats the failure. Wait for the Dashboard to show that the Engine is ready, then confirm Server information with docker version.
The command connects, but shows unexpected containers
This usually means the CLI is connected to another Engine. Check contexts and executable resolution:
|
|
In WSL, run:
|
|
If type -a docker lists several paths, identify the first executable. The Docker Desktop CLI injected through Windows PATH, a CLI installed in the distribution, and a shell alias can coexist. Identify their sources before removing files or changing system PATH.
Containers, images, and volumes belong to their respective Engines. Seeing different results from docker ps -a or docker volume ls after a context change is normal. Confirm the current endpoint before cleaning anything; do not mistake a remote production context for a local test Engine.
An unexpected WSL error or virtual machine startup failure appears
If an error includes HCS_E_HYPERV_NOT_INSTALLED or ERROR_NOT_SUPPORTED, or WSL cannot start a distribution either, check Windows features and hardware virtualization first:
- Is CPU virtualization enabled in BIOS/UEFI?
- Are Virtual Machine Platform and Windows Subsystem for Linux enabled in Windows?
- If Windows runs inside a VM or cloud desktop, is nested virtualization enabled by the host?
- Has the hypervisor been disabled by boot settings or other virtualization software?
- Was an Android emulator or older VM product installed recently and did it change Hyper-V settings?
Task Manager’s Performance > CPU page shows virtualization status. Do not change BCD or Windows features without understanding the existing VM setup. On a managed computer, check organizational policies first.
If wsl -l -v works but only Docker Desktop’s docker-desktop distribution fails, save the full error and timestamp, then collect diagnostics with Docker Desktop’s Troubleshoot > Get support. Do not manually delete docker-desktop or docker-desktop-data, and do not run cleanup commands inside them.
The WSL integration menu is missing or the selected distribution still fails
Confirm that Docker Desktop is not in Windows containers mode, then identify its backend. Docker says full WSL Integration is available only with the WSL 2 engine. In Docker VMM mode, recent versions can run the Docker CLI from WSL distributions, but socket access, direct mounts, and development-tool support have different limits.
Before changing the backend, read the settings documentation for your Docker Desktop version and confirm what your tools need. A working docker command alone does not guarantee compatibility with VS Code Dev Containers, Docker SDKs, or Testcontainers that use the Docker Engine API socket.
If you just enabled integration but the terminal still has its previous environment, run:
|
|
Then reopen the intended distribution. This closes every distribution and the WSL virtual machine. It does not reset files, but it ends unsaved process state.
Do not switch back and forth between WSL 1 and 2, unregister a distribution, reset Docker Desktop to factory defaults, or delete a virtual disk just to refresh integration. These actions can lose data and are usually unnecessary for initial troubleshooting.
Docker VMM commands work, but mounts or development tools do not
Docker VMM and the WSL 2 engine interact differently. In VMM mode, WSL can call the Docker CLI through Windows interop. Current documentation lists limitations: there is no Linux Docker socket, and only files on Windows drives can be bind-mounted directly. Tools such as Docker SDKs, Testcontainers, and Dev Containers that depend on a socket may not work.
A project started from PowerShell typically uses a C:\... path, while the same Windows drive appears as /mnt/c/... in WSL. If an error mentions a path inside the distribution, such as /home/..., and you use Docker VMM, check whether that workflow is supported. Do not assume that changing a Linux path to a Windows path preserves permissions, file watching, or performance.
For Linux development with the WSL 2 engine, Docker recommends storing project files in the distribution’s Linux filesystem to reduce cross-filesystem operations. If Windows tools and Linux containers both need frequent access to the same project, evaluate permissions, case sensitivity, file watching, and mount performance before choosing a primary workspace.
When a mount fails, check that the source path exists, which directory the command runs from, which backend is active, and whether the target distribution has integration enabled. Keep /app, C:\project, and /mnt/c/project distinct.
WSL has a distribution, but Docker Desktop cannot find it
List distributions from Windows and check the version column:
|
|
If a distribution name has spaces or different capitalization, select the exact name shown. A new distribution may default to WSL 1; Docker Desktop’s WSL 2 integration requires a WSL 2 distribution. Back up before converting:
|
|
The export contains distribution data and may take substantial disk space. Confirm that the backup file exists and is accessible before converting. Do not use the example name for a different important distribution.
If you renamed, moved, or imported a distribution, check its registered name and state with wsl -l -v. Do not delete registration entries to make it reappear. A distribution registration, its disk file, and Docker Desktop’s managed virtual disk are separate objects.
Integration stops working after a Docker Desktop update
Do not immediately clear images and containers after an update. Record the Docker Desktop version, wsl --version, distribution name, backend mode, and full error. Then check Docker’s release notes for the matching version combination.
Docker’s recent release notes documented an issue where integration with user distributions failed on WSL 2.6.x and later because of a zero-byte proxy binary, causing Permission denied or Exec format error. A later release fixed it. If your error matches, check the actual Docker Desktop version and update channel. Do not replace internal files by following unverified forum instructions.
The release notes also document a fix for the Docker CLI in integrated distributions becoming temporarily unavailable after Resource Saver stopped the virtual machine. Whether it applies depends on your versions. A diagnostic ID and reproducible steps are more useful than a guess based on one matching keyword.
To reduce a reproduction, quit Docker Desktop, run wsl --shutdown, restart Docker Desktop, wait for the Engine, open one target distribution, and run docker version. Record the time and output at each step. If only one distribution fails, focus on it. If all WSL commands fail, return to WSL and Windows feature checks.
Change one setting at a time. For example, update WSL and verify it before changing the Docker Desktop backend. Updating WSL, switching Hyper-V/VMM, resetting data, and reinstalling all at once removes causal clues and may introduce new variables.
If you suspect a regression, check the Docker Desktop About page and the official release-note dates before deciding whether to upgrade or roll back under your organization’s policy. Do not download old installers from unknown sources or overwrite internal files in docker-desktop with forum scripts.
An image pull failure is not necessarily a WSL integration problem
If docker version shows a Server but docker pull fails with DNS, proxy, TLS, or authentication errors, the CLI has usually connected to the Engine. Check Windows networking, the Docker Desktop proxy, registry credentials, and registry address instead of toggling WSL integration.
Start with a status check that does not pull an image, and record the complete error. If the problem occurs only on a company network or with a VPN enabled, compare DNS, proxy policy, and corporate certificate requirements under the same network conditions. Do not disable a company security proxy or bypass certificate validation to test.
A failed docker compose up can also come from project configuration or the application. Run docker compose config to inspect the resolved Compose file, then identify whether the failure occurs during image pull, container creation, volume mounting, or application startup. Follow the WSL integration branch only when the command cannot connect to the daemon.
If the Engine connects but Compose environment variables do not reach the container, see the Docker Compose environment variable troubleshooting guide. For database readiness and service startup order, see the Compose depends_on and healthcheck guide.
Disk space, resets, and backup boundaries
Docker Desktop’s WSL 2 engine data is usually stored under a Docker WSL data location in the user profile, but settings may change it. Deleting that virtual disk may permanently remove local images, containers, and volume data. Clean up data and Reset to factory defaults are not lossless restart options.
Before cleanup, confirm that database volumes, images, or container data you need have independent backups. A rebuildable container does not make its volume data rebuildable. In a business environment, check retention and backup policies first.
Prefer Docker Desktop’s diagnostics, normal quit, and restart flow. Consider wiping data or resetting to factory defaults only after you understand the scope and verify a backup.
Collect diagnostics and verify the fix
When Docker Dashboard opens, select Get support in the Troubleshoot menu. Wait for diagnostics collection to finish, upload it, and save the Diagnostic ID. If the UI cannot start, use the official docker desktop diagnose command where available; command-line support depends on your Docker Desktop version.
Include the following information when reporting the problem:
- Windows and Docker Desktop versions.
- Output from
wsl --version,wsl --status, andwsl -l -v. - Target distribution name, WSL version, and Docker Desktop backend.
- Full
docker versionoutput from both PowerShell and WSL. docker context show, and whetherDOCKER_HOSTorDOCKER_CONTEXTis set.- The complete error, when it first appeared, whether an update preceded it, and the Diagnostic ID.
After the fix, verify separately in PowerShell and the target WSL distribution:
|
|
|
|
The integration check is complete only when both terminals connect to the intended local Engine and docker version shows Client and Server information. Then run docker compose config and the project’s startup command to confirm mounts, networking, and environment variables.
Frequently asked questions
Docker works in Windows, but Ubuntu has no docker command. Should I reinstall?
First enable the Docker Desktop WSL 2 engine and Ubuntu integration, then shut down and reopen WSL. Do not install a second Docker Engine in Ubuntu as the first step.
What does it mean when docker version shows only Client?
The CLI runs, but it has not received a response from the Engine Server. Check Docker Desktop startup, the current context, DOCKER_HOST, and the backend mode.
Does wsl --shutdown delete containers?
It stops every WSL distribution and the WSL virtual machine; it is not a data deletion command. Unsaved state in running programs is interrupted. Restart Docker Desktop and the target distribution, then verify again.
Can I delete docker-desktop-data to fix startup?
Do not treat deleting an internal distribution as a routine repair. It may erase local images, containers, or volumes. Collect diagnostics and check official recovery steps first; consider data-level operations only after confirming a backup.
Why does docker work in WSL, but Dev Containers or Testcontainers fail?
A working command does not mean every use of the Docker socket and Engine API is available. Confirm the Docker Desktop backend first; Docker VMM has separate socket and mount limitations.
Official references
- Docker Desktop WSL 2 backend: WSL requirements, integration settings, and Docker VMM boundaries.
- Docker Desktop troubleshooting topics: virtualization and WSL startup errors.
- Docker Desktop troubleshooting and diagnostics: Diagnostic IDs, logs, and support workflow.
- Docker Desktop release notes: check whether a specific version fixes a WSL integration issue.
- Microsoft WSL basic commands: update, inspect, shut down, and export distributions.