Reclaim Docker Desktop space: prune, resize the disk image, reset

Part of: Docker disk space on Mac: Docker.raw, images and build cache explained (Docker)

There are three ways to get space back from Docker Desktop, and they differ a lot in what they cost. Pruning unused data is the gentle one. Lowering the disk image size and resetting the disk image both delete all your images and containers. Try them in that order, and stop when you have enough space.

Step 1: look before you remove

Run this read-only command first:

docker system df

It shows images, containers, local volumes and build cache, each with a total and a reclaimable amount. If one row is clearly the biggest, that is where to start. Docker’s Mac FAQ suggests the same first step, with the -v option for a per-item list.

Step 2: prune what is unused

Docker’s pruning guide describes a separate prune command for each kind of data:

• Containers: removes stopped containers.
• Images: by default removes only dangling images, meaning untagged ones nothing refers to. An option widens it to all unused images.
• Volumes: by default removes only anonymous volumes not used by a container. The guide warns about this one, and named volumes need an extra option.
• Build cache: removes saved build layers. See the build cache guide.
• System prune: one command that covers several of the above. The guide says named unused volumes are left alone unless you ask for them.

Every prune command asks for confirmation. Read it.

Docker’s FAQ adds that space is only freed when images are deleted, and not automatically when files are deleted inside running containers.

Why the file may still look big

After pruning, the disk image file can still look large in Finder. It is a sparse file, so its maximum size and its real size differ. The Docker.raw guide shows how to read both. Check the real size with du before you decide the space has not come back.

Step 3: lower the disk image size

In Docker Desktop, the Advanced page under Resources has a setting for the maximum disk space the engine can use. Docker’s Mac FAQ describes a disk image size slider there and gives this warning: reducing the maximum size deletes the current disk image, so all containers and images are lost.

Do this only when pruning did not give you enough, and when nothing in Docker is something you cannot recreate. Export or back up volume data first.

Step 4: clean up data or reset

The Docker Desktop Troubleshoot menu has two options that are easy to mix up. Docker documents them like this:

• Reset to factory defaults resets all options on Docker Desktop to their initial state, the same as when it was first installed.
• Clean up data is described as a disk image reset that destroys all Docker containers and images local to the machine, while keeping all settings.

I did not test either option, because I do not have Docker Desktop on the machine I used for this guide, so read the current Docker documentation before you click.

Which one to pick

• Disk full and you only want some headroom: prune stopped containers, then build cache.
• Disk image far bigger than your real use, and you can afford a fresh start: the size limit or clean up data.
• Not sure what is in a volume: leave volumes alone until you do.

For the whole picture, see the overview. If you use Colima, read the Colima guide instead, because it works differently.

How DiskJoy fits in

DiskJoy is our product. It is pre-alpha: it scans and shows reclaimable space, but cleanup is not built yet, so it does not prune, resize or reset anything in Docker. The download page shows the current status of the scan.