Verify Docker Desktop After Installation on Windows

After installing Docker Desktop, verify the terminal-to-engine path before reinstalling anything. A working docker command proves that the CLI can run. It does not prove which engine it selected, whether that engine answers, or whether a container can start.

This checklist is for PowerShell on Windows with Docker Desktop already installed and its local Linux-container engine intended. For the installer and WSL prerequisites, use the Windows installation course lesson. Keep any existing application containers running while you perform these checks.

Identify the command and selection overrides

Open a new PowerShell window after installation, then run these read-only checks. The last two lines report only whether overrides are set, without printing their values.

Get-Command docker -All | Select-Object Name,Source
docker --version
docker context show
docker context ls
"DOCKER_CONTEXT set: $([bool]$env:DOCKER_CONTEXT)"
"DOCKER_HOST set: $([bool]$env:DOCKER_HOST)"

Get-Command shows which docker executable PowerShell resolves. docker --version tests that executable without needing an engine connection. The context list shows configured endpoints; the selected context and environment overrides can explain why a terminal targets a different engine than expected.

If docker is not found, reopen the terminal and inspect its command path before rerunning an installer. If it resolves to an unexpected executable, resolve that path choice before interpreting later errors. Do not delete contexts or clear environment settings merely because several exist.

Check an explicit local Desktop context

The example uses desktop-linux, the local Linux Desktop context on the test machine. Confirm the appropriate name in your context list. The endpoint guard below is specifically for a local Windows named pipe; stop if the context points to a remote server or another transport.

$checkContext = 'desktop-linux'
$checkEndpoint = docker context inspect $checkContext --format '{{.Endpoints.docker.Host}}'
if ($LASTEXITCODE -ne 0) { throw 'The selected context is unavailable.' }
if ($checkEndpoint -notlike 'npipe:////./pipe/*') {
    throw 'Expected a local Windows named-pipe endpoint; inspect the selected context.'
}
$checkEndpoint
docker --context $checkContext version --format 'client={{.Client.Version}} server={{.Server.Version}} os={{.Server.Os}}'
if ($LASTEXITCODE -ne 0) { throw 'The selected engine did not answer.' }
docker --context $checkContext info --format 'os={{.OSType}} platform={{.OperatingSystem}}'
if ($LASTEXITCODE -ne 0) { throw 'Engine information is unavailable.' }

Expect a local named-pipe endpoint, both client and server versions, and Linux as the engine OS. The platform line should identify Docker Desktop for this checklist. If it identifies a different engine or OS, confirm the intended target before creating anything. Commands were verified with CLI and Engine 29.6.2; exact paths and version numbers can differ.

Passing --context explicitly selects the context for that command, including when DOCKER_HOST or DOCKER_CONTEXT overrides are present. It does not change the saved default context. That lets you test the intended Desktop connection while leaving another project's context selection intact.

Run one disposable container

Continue only after the explicit context answers and identifies the intended local Linux Desktop engine. Run this in the same PowerShell session so $checkContext remains defined. It creates one uniquely named container, publishes no ports, mounts no project folders and removes that container after it exits.

$probeName = 'xtdemo-desktop-check-' + [guid]::NewGuid().ToString('N').Substring(0,8)
docker --context $checkContext run --rm --name $probeName hello-world:latest
if ($LASTEXITCODE -ne 0) { throw 'The container check failed; read the error above.' }
$remaining = @(docker --context $checkContext ps -a --filter "name=^/$probeName$" --format '{{.Names}}')
if ($LASTEXITCODE -ne 0) { throw 'Could not verify container cleanup.' }
if ($remaining.Count -gt 0) { throw 'The probe container is still present.' }
'PASS: container ran successfully and its temporary container was removed.'

Look for Hello from Docker!, a successful command exit and the final PASS line. On a first run, Docker may download the public hello-world image; that step needs registry access. Later runs can use a cached image. --rm removes the container, while the image remains cached.

A successful cached run proves the selected engine can create and execute this image. It does not prove that registry access currently works, that your application image builds, or that a web port or persistent volume is configured correctly. Those are separate checks for the application.

Locate the failed layer

Keep the exact failed command and its error together. A wrong endpoint, a stopped engine and a denied image download need different fixes. Avoid switching engine modes, resetting Desktop or pruning data as a routine verification step; those actions can disrupt existing projects and do not identify the failing layer.

Verify that the probe left no container

The script checks the exact generated name after the run and refuses to print PASS if it remains. If an interrupted run leaves it behind, inspect that exact container first:

docker --context $checkContext ps -a --filter "name=^/$probeName$" --format '{{.Names}} {{.Status}}'
docker --context $checkContext inspect $probeName --format '{{.State.Status}}'

For a confirmed probe whose state is created or exited, remove only that exact name. This command does not force removal of a running container:

docker --context $checkContext rm $probeName

Do not use a broad prune command or remove unrelated application containers. An empty name-filter result after the successful check is the expected outcome.

Try an override mismatch

Suppose a shell has an override pointing to another context. Would a successful bare docker version prove the local Desktop engine is healthy?

Answer: no. It may be reporting a different engine. Compare the selected context and endpoint, then run the explicit-context checks. A deliberate missing-context override in an isolated test shell made the bare command fail while --context desktop-linux still reached the local engine. Keep the override only if that shell is meant for its original project; the checklist does not require changing the saved default.

References: Docker context selection and docker run and automatic container removal.