Why Docker takes so much disk space on Mac, and the fix

Where Docker's space actually is

Docker Desktop runs containers inside a small Linux virtual machine. That machine's disk is a single file on your Mac, at ~/Library/Containers/com.docker.docker/Data/vms/0/data/Docker.raw.

The file is sparse. Finder may show it at its maximum allowed size even when far less is in use. The command below shows both figures: the first column is the space really taken on your disk, and the size later in the line is the maximum.

This is why deleting a container's files from inside macOS is not possible, and why the folder looks like one enormous item in any disk tool.

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

See what is using the space

With Docker Desktop running, ask Docker for a breakdown. The command below lists four things: images, containers, local volumes and build cache, with the total size of each and how much of it is reclaimable.

Add -v for a line per image, container and volume. It is worth a minute to read. On most developer machines the large items are old images and build cache, but if volumes are large, that is data, and it needs more care.

docker system df

Step 1: the safe prune

Start with the command below. It removes stopped containers, networks not used by any container, dangling images, which are layers no longer tagged or referenced, and unused build cache. Docker lists what it will remove and asks you to confirm.

It does not remove images that have a tag, running containers, or volumes. For many people this is enough.

Nothing here is hard to get back. A removed container can be created again from its image, and build cache only costs you a slower next build. The one thing to check is whether a stopped container holds files you wrote inside it and never copied out.

docker system prune

Step 2: unused images and build cache

If you need more, go after images and build cache specifically.

• docker image prune -a removes every image that no container is using, tagged or not. You will pull or build them again when you next need them.
• docker builder prune removes build cache. Add -a to remove all of it, not only the dangling part. Your next builds start cold and take longer.
• docker system prune -a does both of the above together with the Step 1 cleanup.
• docker container ls -a shows stopped containers. One you still want may be keeping a large image in use.

Step 3: volumes, with care

Volumes are where containers keep data that should survive: database files, uploads, package caches. Pruning them can delete real work, so look first.

List them with the first command below, and check which projects they belong to. The second command removes anonymous volumes that no container uses. Adding -a extends that to named volumes that no container uses, which is where a local development database usually lives.

If a volume matters, back it up or dump the database before you prune. Volumes from a Compose project can be removed together with that project using docker compose down -v, run in the project folder.

docker volume ls
docker volume prune

Getting the space back on your Mac

After pruning, Docker Desktop hands the freed space inside the virtual disk back to macOS. With the Docker.raw format this normally happens within moments, though tools that show the file's maximum size will show no change. Run the ls command from the first section again to see the real figure.

To stop it growing so large in future, open Docker Desktop, go to Settings, then Resources, and lower the disk usage limit. Docker warns you if the change would erase existing data.

If you want to start over completely, Docker Desktop's Troubleshoot screen has a Clean / Purge data option and a reset to factory defaults. Both delete all images, containers and volumes.

What is not inside Docker.raw

A few things Docker-related sit outside the virtual disk. Folders you mount into containers are ordinary folders on your Mac and are not touched by any prune. Project folders hold their own build output, such as node_modules. And if you remove Docker Desktop, its helpers, group containers and the ~/.docker folder stay behind unless you remove them too.

Where Diskzy fits

Diskzy shows how large Docker.raw really is on the disk map, so you know when it is time to prune inside Docker. It does not shrink the file for you.

If you decide to remove Docker Desktop altogether, Diskzy's Uninstall removes the app together with what it left behind, including containers, launch agents and privileged helpers. Everything goes to the Trash.