Docker ate your disk.
Get it back safely.

Docker Desktop runs your containers inside a small Linux virtual machine. Everything that machine stores — images, containers, volumes and build cache — lives in a single, large disk image file on your Mac. Unless you moved it, the file is here:

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

Docker Desktop shows the location in Settings → Resources → Advanced, under Disk image location. If you moved the disk image there, use that path instead in the commands below.

Storage settings has no Docker category. Apple describes System Data as the place for files that fit nowhere else, virtual machine files included, so a large Docker.raw is usually a big part of that number.

Docker.raw is a sparse file. It has a maximum size — the disk limit you set in Docker Desktop — but only the blocks the virtual machine has actually written take space on your disk. Some tools report the maximum, so the file can look several times bigger than it is. To see both numbers, run:

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

The first column is the space the file really takes. The size column, before the date, is the maximum. On the Mac this guide was checked on, the first column read 57G and the size column 461G. For the real size alone:

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

The real size is what your disk loses, and the only one worth tracking. Docker Desktop also shows it, next to the maximum, in Settings → Resources → Advanced.

Ask Docker. This command is read-only:

docker system df

It prints one row each for images, containers, local volumes and build cache, with their total size and a RECLAIMABLE column: Docker's estimate of what removing unused objects of that type would free. Treat that column as a rough guide. Images share layers, and a layer only goes away when every image that uses it is gone.

For the details, add -v:

docker system df -v

• Images come with SHARED SIZE, UNIQUE SIZE and CONTAINERS. Unique size is roughly what removing that one image frees. CONTAINERS is how many containers, running or stopped, use it.
• Containers show the size of what each one wrote on top of its image, and its status.
• Local volumes show LINKS, the number of containers attached. A volume with 0 links is unused, but it may still hold the only copy of a database.
• Build cache lists cache records from docker build, with when each was last used.

Docker generally keeps unused objects until you ask it to remove them. Each type has a prune command, and each asks for confirmation unless you add -f. Docker's pruning guide describes them all; here is what each costs you.

An image counts as used while any container exists for it, even a stopped one. If you prune containers first, docker image prune -a afterwards removes more.

The build cache and dangling images are usually the safest large win. Start there, check docker system df again, and go further only if you need to.

Only if you know what is in the volumes. Volumes are where containers keep data that should outlive them: Postgres and MySQL data directories, uploaded files, package caches. Docker never removes them automatically for exactly that reason.

“Unused” only means no container is attached right now. If you removed a project's containers with docker compose down, its database volume is unused until the next docker compose up, and docker volume prune -a would delete it. List the candidates first:

docker volume ls --filter dangling=true

Then remove the ones you recognize by name with docker volume rm <name>, rather than all at once. The same care applies to docker compose down -v, which removes the named volumes a Compose file declares.

It should, but not always at once. Docker's Mac FAQ says it can take a few minutes for the space to come back to macOS, that space is freed when images are deleted, and that deleting files inside a running container doesn't free space automatically. To ask Docker Desktop to give unused blocks back right away, the FAQ suggests:

docker run --privileged --pid=host docker/desktop-reclaim-space

To check what came back, compare du -h on Docker.raw before and after, or simply watch free space in Finder. The maximum size that ls -l shows doesn't change when you prune; it is a ceiling, not usage.

You can, but treat it as a factory reset of your Docker data. Every image, container, volume and build cache record is inside that one file, and none of it survives.

If that is really what you want, let Docker Desktop do it. Its Troubleshoot menu has a Clean up data option, and Docker's troubleshooting page says a disk image reset destroys all local containers and images while keeping your settings. Back up any volume you care about first.

Lowering the disk size limit has the same effect: the Mac FAQ says the current disk image is deleted and all containers and images are lost. Moving the file is different. To put it on a bigger drive, use Disk image location in Settings rather than Finder; Docker warns that moving it by hand can make Docker Desktop lose track of it.

• Set a disk limit early. Settings → Resources → Advanced has a disk usage limit. Docker's engine can't use more than that. Since lowering it later wipes the disk image, pick a size you can live with while it is still cheap to change.
• Trim the build cache by age or size. Instead of clearing everything, keep what you used recently. --filter until=168h keeps cache records used in the last week, and --max-used-space trims the oldest records until the cache fits:

docker builder prune --filter until=168h
docker builder prune --max-used-space 20gb

• Use --rm for throwaway containers. A container started with docker run --rm removes itself when it exits, so stopped containers don't pile up.
• Check after big pulls and rebuilds. New tags of the same image leave the old one behind until you remove it. docker system df takes a few seconds and tells you when it is time.

Docker is rarely the only developer tool filling a Mac. Project folders full of node_modules and package-manager caches are usually next on the list.

Specula's Docker page shows the allocated size of Docker.raw — the real size, not the maximum — next to what the docker command-line tool reports. It estimates how much clearing the build cache and removing unused images would free, counting each unused image by its unique size, and lists unused images so you can remove them one by one.

Clearing the build cache and removing all unused images are two bulk actions, each confirmed first. Images are removed with docker image rm, which refuses an image a container still uses. Specula never cleans volumes. If your active Docker context points to another machine, Specula shows a warning, runs only read-only commands and refuses to clean up. Docker.raw and the folders that contain it can't be deleted from Specula at all. On the free-space chart, a Docker cleanup gets a marker that shows the space that actually came back to your Mac.