Docker disk space on Mac: reclaim it safely

Why does Docker use so much space on a Mac?

Docker containers need a Linux kernel, so Docker Desktop runs a small Linux virtual machine. Docker's documentation puts it this way: Docker Desktop "stores Linux containers and images in a single, large 'disk image' file in the Mac filesystem". By default that file is:

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

It's a sparse file: it has a maximum size, but only uses the space actually written into it. Finder may show the maximum, which is why people panic. To see the real number:

# the first column is the space actually used on disk
$ ls -klsh ~/Library/Containers/com.docker.docker/Data/vms/0/data/Docker.raw

You can also see the path in Docker Desktop > Settings > Resources > Advanced, under Disk image location.

The space inside grows with every image you pull, every build layer, every stopped container and every volume. On a Mac that builds images regularly it's easy to reach tens of gigabytes, and Docker doesn't clean up after itself unless you ask.

How do I see what's using Docker's disk space?

# summary: images, containers, local volumes, build cache
$ docker system df

# the same, item by item
$ docker system df -v

The RECLAIMABLE column is the useful one: it's what Docker could remove without touching anything in use right now.

Shedi cleans Docker with Docker's own commandsUnused images, stopped containers and build cache are listed with their sizes; volumes are shown separately as your files. Nothing runs until you press Clean.

Get Shedi

Which Docker prune commands are safe?

Run these one at a time so you know what each one freed. Each asks for confirmation (add -f to skip the prompt), and none of them uses the Trash: what they remove is gone, though everything except volumes can be pulled or rebuilt.

Stopped containers. Containers you've exited but not removed. Their writable layer, including any files written inside the container (not in a volume), is deleted.

$ docker container prune

Images. Without flags, this removes only dangling images (untagged layers left behind by rebuilds). With -a, it removes every image that no container uses, including ones you pulled on purpose.

# dangling images only
$ docker image prune

# every image not used by at least one container
$ docker image prune -a

Build cache. Layers cached by docker build and BuildKit. Often the biggest single item on a Mac that builds a lot. Without flags it removes dangling cache; -a removes all unused build cache.

$ docker builder prune
$ docker builder prune -a

Networks. Tiny, but tidy:

$ docker network prune

All prune commands accept a filter if you only want to remove older things:

# only images unused for more than a week
$ docker image prune -a --filter "until=168h"

What about docker system prune -a?

docker system prune runs most of the above at once. Docker's reference describes it as removing "all unused containers, networks, images (both dangling and unused), unused build cache, and optionally, volumes". The flags matter:

Why are Docker volumes different?

Volumes are where containers keep data that should survive the container: a local Postgres database, uploaded files, a search index. Docker's docs note that a volume's contents "exist outside the lifecycle of a given container". That's the point of them, and it's why you should never prune them on autopilot.

# all volumes
$ docker volume ls

# volumes not used by any container
$ docker volume ls -f dangling=true

# remove one specific volume you've checked
$ docker volume rm <volume-name>

docker volume prune removes unused volumes. In current Docker versions it only removes anonymous volumes by default; adding -a also removes named volumes that no container uses, which is where local databases usually live.

How do I shrink or limit the Docker disk image?

Pruning frees space inside the disk image, and because the file is sparse, your Mac usually gets that space back. If it doesn't seem to, Docker's Mac FAQ suggests this command to reclaim space after deleting files:

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

To cap how big the disk image can grow, open Docker Desktop > Settings > Resources > Advanced and set the Disk usage limit.

Why does Docker fill up again so quickly?

Pruning is maintenance, not a cure. A few habits decide how fast the space comes back:

• Rebuilding often. Each docker build after a dependency change creates new layers, and the old image becomes dangling. Build cache grows with every variation of every Dockerfile you build.
• Many projects, many base images. Each project pulling its own node, python or postgres tag adds a few hundred megabytes to a few gigabytes. Sharing base image versions across projects where you can helps.
• docker compose up without down. Stopped containers and their anonymous volumes accumulate. docker compose down removes a project's containers and networks; docker compose down -v also removes its volumes, so use that only when you're sure the data is disposable.
• Multi-platform builds. Building for both linux/amd64 and linux/arm64 stores layers for each.

Checking docker system df once a month, and running docker builder prune when the build cache line gets large, keeps most Macs in check without ever touching volumes.

What should I avoid?

• Deleting Docker.raw in Finder. It destroys every image, container and volume at once. Prune inside Docker, or use Docker Desktop's own reset options, so you decide what goes.
• docker volume prune -a without looking. That's how local databases disappear.
• Pruning right before a flight. -a removes images you may not be able to pull offline.

If you use another Docker runtime (OrbStack, Colima, Rancher Desktop), the docker commands above work the same, but the disk image lives somewhere else; check that tool's documentation for its location.

A sensible routine

$ docker system df
$ docker container prune
$ docker image prune -a --filter "until=168h"
$ docker builder prune
$ docker system df   # compare

Volumes: review with docker volume ls and remove individually. Docker is one of three usual suspects on a developer Mac; the others are Xcode and node_modules, and the full cache reference covers the rest. Shedi runs the same Docker commands for you, after showing exactly what each one will remove; Docker's disk image itself is never deleted directly.

Sources

• Docker Docs: Prune unused Docker objects
• Docker Docs: docker system prune
• Docker Docs: docker builder prune
• Docker Docs: Volumes
• Docker Docs: docker compose down
• Docker Docs: Docker Desktop for Mac FAQ
• Docker Docs: Docker Desktop settings