18.1.1.4 Desktop VM Runtime

The Desktop VM runtime is the actual virtual machine instance Docker Desktop maintains behind the scenes, and beyond which specific backend technology implements it, this VM has its own lifecycle concerns worth understanding directly: disk image growth over time, restart and reset procedures, and how to diagnose the VM itself when Desktop becomes unresponsive in a way that troubleshooting individual containers cannot resolve.

Virtual disk growth over time

The VM's underlying disk image, often a qcow2 or similar virtual disk format depending on platform and backend, can grow substantially over time as images, containers, and volumes accumulate within it, and this growth does not always shrink automatically even after that content is removed from within Docker itself:

docker system df

~/Library/Containers/com.docker.docker/Data/vms/0/data/Docker.raw

A virtual disk file reported as occupying considerably more space on the host than docker system df shows as actually in use within Docker is a common, specific symptom of this disk growth not being automatically reclaimed, even after legitimate cleanup has already occurred inside the Docker environment itself.

Reclaiming disk space at the VM level

Beyond Docker's own pruning commands, which clean up content within the VM, Docker Desktop provides its own mechanism for actually compacting or resetting the underlying virtual disk to reclaim the host-level space that internal cleanup alone does not automatically return:

Troubleshoot > Clean / Purge data

docker system prune -af --volumes

Running Docker's own pruning first, then using Desktop's dedicated disk reclamation feature if the underlying virtual disk file's actual host-level size still does not shrink correspondingly, addresses this two-layer cleanup requirement that a purely Docker-level prune alone does not always fully resolve.

Restarting versus resetting the VM

A simple restart of Docker Desktop restarts the underlying VM without discarding any of its content, which is the appropriate first step for a Desktop instance that has become sluggish or unresponsive; a full reset, by contrast, discards the VM's entire content, every image, container, and volume within it, and should be reserved for situations where a restart alone does not resolve the issue:

Quit Docker Desktop, then relaunch it

Troubleshoot > Reset to factory defaults

Understanding this distinction before reaching for the more drastic reset option avoids unnecessarily discarding locally built images or volume data that a simple restart might have been entirely sufficient to resolve on its own.

Diagnosing a VM stuck in a starting state

Docker Desktop occasionally becomes stuck in a "starting" state that never actually completes, which is a VM-level startup problem rather than anything related to individual containers, and Desktop's own diagnostic logs provide the most direct path to understanding what specifically is preventing the VM from completing its startup sequence:

Troubleshoot > Get support (generates a diagnostic bundle)

cat ~/Library/Containers/com.docker.docker/Data/log/vm/dockerd.log

Reviewing these logs directly, or providing the generated diagnostic bundle when seeking support, surfaces the actual underlying cause far more reliably than guessing based on the generic, uninformative "starting" status the main interface displays while stuck.

Resource contention with other virtualization software

On a machine also running other virtualization software, a separate hypervisor, another VM platform, the Desktop VM can experience resource contention or, in some cases, an outright conflict preventing it from starting at all, since multiple virtualization technologies attempting to use the same underlying hardware virtualization features simultaneously do not always coexist cleanly:

docker info

Error: failed to start Docker Desktop VM

Confirming whether other virtualization software is active simultaneously, and consulting Docker Desktop's own documentation for known compatibility considerations with that specific other software, is a useful diagnostic step when the VM fails to start in a way unrelated to anything Docker-specific seems to explain.

Memory and CPU contention from the VM's own footprint

Beyond the explicitly configured resource limits, the VM itself has a baseline resource footprint simply for existing and running its own internal operating system, separate from whatever containers are actually running within it, which is worth accounting for when reasoning about a host machine's overall resource availability, particularly on a machine with otherwise limited total capacity:

ps aux | grep -i "Docker Desktop"

Reviewing the actual host-level process list for Docker Desktop's own VM-related processes provides a more complete picture of its total resource footprint than only considering the resource limits configured for individual containers running within it.

Common mistakes

• Assuming Docker's own pruning commands alone fully reclaim host-level disk space, without checking whether the underlying virtual disk file's actual size has correspondingly shrunk.
• Reaching for a full VM reset as the first troubleshooting step rather than trying a simple restart first, unnecessarily discarding existing images and volume data.
• Not reviewing Docker Desktop's own diagnostic logs when the VM becomes stuck starting, relying instead on the generic, uninformative status display alone.
• Overlooking resource contention or conflict with other virtualization software running simultaneously on the same host as a potential cause of VM startup failure.
• Reasoning about host resource availability based only on configured container limits, without accounting for the VM's own baseline resource footprint separate from anything running inside it.

The Desktop VM runtime has its own distinct lifecycle concerns, disk growth that internal pruning alone does not always fully reclaim, a meaningful distinction between restarting and fully resetting, and its own diagnostic logs for startup failures, all of which are separate considerations from the underlying backend technology choice and worth understanding directly when troubleshooting Docker Desktop at the VM level rather than at the level of individual containers.