Docker is eating my Mac's disk: how to reclaim it

Why Docker uses so much space on a Mac

Containers need a Linux kernel, so Docker Desktop runs a small Linux virtual machine on your Mac. Everything Docker stores lives on that virtual machine’s disk, which is one file on your Mac:

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

Images, stopped containers, volumes with database files, and the build cache all live inside it. Docker Desktop shows the exact location in Settings > Resources > Advanced.

Because everything sits in one file, a disk analyzer or Finder sees a single large item instead of the images and volumes inside it. To understand what is really there, you ask Docker.

The Finder size is not the real size

Docker.raw is a sparse file. It has a maximum size, set in Docker Desktop, but only takes up the space actually written to it. Many tools, including Finder’s size column, show the maximum. Terminal can show both:

~ % cd ~/Library/Containers/com.docker.docker/Data/vms/0/data
data % ls -lh Docker.raw
-rw-r--r--@ 1 you  staff    64G Oct 29 09:12 Docker.raw
data % du -h Docker.raw
 23G	Docker.raw

ls shows the maximum (64 GB here). du shows what the file really occupies on your disk (23 GB). The second number is the one that matters for free space.

See what is inside

Docker’s own summary splits the space by type:

~ % docker system df
TYPE            TOTAL     ACTIVE    SIZE      RECLAIMABLE
Images          41        6         18.2GB    14.9GB (81%)
Containers      9         2         1.1GB     1.0GB (90%)
Local Volumes   14        3         3.4GB     2.7GB (79%)
Build Cache     212       0         6.8GB     6.8GB

• Images are the base layers and builds you pulled or created. Unused images are ones no container refers to.
• Containers are the writable layers of containers, including stopped ones you forgot about.
• Local Volumes hold persistent data, such as a Postgres or MySQL database for a project. This is the category to treat with care.
• Build Cache is BuildKit’s cache of build steps. It is often the fastest growing part and is always safe to clear.

docker system df -v lists every image, container and volume with its size, so you can see which ones are large.

Prune safely, one type at a time

Docker has a prune command for each type. Running them one at a time lets you see what goes.

# build cache: always safe, rebuilds on the next build
~ % docker builder prune
# stopped containers
~ % docker container prune
# dangling images (untagged leftovers of rebuilds)
~ % docker image prune
# every image not used by a container
~ % docker image prune -a

Each command lists what it will remove and asks for confirmation. Images you remove are pulled again the next time you need them, so the main cost is download time.

If you want all of that in one step, docker system prune removes stopped containers, unused networks, dangling images and dangling build cache. Adding -a also removes every unused image and all unused build cache, not only dangling ones.

Volumes, carefully

List the volumes and check which project each one belongs to:

~ % docker volume ls
~ % docker system df -v

Then remove the ones you are sure about by name with docker volume rm <name>. docker volume prune removes anonymous volumes that no container uses; on current Docker versions, add -a to include named volumes as well. If a volume holds data you might want later, export it first, or keep it.

When the disk image does not shrink

After pruning, docker system df shows less, but your free space may not change right away. Docker Desktop returns freed space to macOS in the background, which can take a few minutes. Check again with du -h Docker.raw after a short while.

Space is only freed when images, containers or volumes are deleted. Deleting files inside a running container does not shrink the disk image.

If the real size stays high, Docker’s documentation suggests running this to reclaim space on demand:

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

Limit or move the disk image

Two settings in Settings > Resources > Advanced help on a Mac with a small internal disk:

• Disk image size sets the maximum size of Docker.raw. Lowering it deletes the current disk image, so every image, container and volume is lost. Back up volumes you need first.
• Disk image location moves the file, for example to an external SSD. Use the Browse button there. Do not move Docker.raw in Finder, because Docker Desktop then loses track of it.

Other Docker setups

If you use an alternative to Docker Desktop, the same commands work, but the data lives elsewhere. Colima keeps its virtual machines under ~/.colima, OrbStack and Podman keep theirs in their own folders, and each has its own disk image that grows the same way. In each case, prune through docker (or podman) commands rather than deleting the tool’s files.

A short routine

For most developers, this keeps Docker under control:

1. Run docker system df once a month.
2. Clear the build cache with docker builder prune.
3. Remove unused images with docker image prune -a.
4. Review volumes by name, and only remove what you recognize.