Why Docker.raw Is Huge on a Mac, and How to Get Its Space Back

$ ls -lh ~/Library/Containers/com.docker.docker/Data/vms/0/data/Docker.raw
$ du -h ~/Library/Containers/com.docker.docker/Data/vms/0/data/Docker.raw
$ docker system df
$ docker image prune -a

I went looking for what was filling my Mac, and Docker’s folder sat near the top of the list. ls read Docker.raw as 1.0T, which can’t be what it occupies. I measured it, pruned, and watched how much of the space came back and when. This page is part of a series on cleaning up a developer Mac’s disk. If you haven’t yet found out that Docker is what fills your disk, finding what is taking up the space comes first; you don’t need it to follow the steps here.

The first prune run below was on an earlier engine, 29.6.2, before Docker Desktop was updated.

Read the real size of Docker.raw

Docker Desktop keeps its Linux containers and images in one disk image file, Docker.raw (Docker’s Mac FAQ (opens in a new tab)). Compare what ls and du say about it:

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

ls printed 1.0T in both runs, and du printed 15G on one day and 14G on another (du -h shows GiB as G). The file is sparse: its maximum size is the disk limit, 1.0T here, and it occupies only the blocks that have been written. du counts those blocks, so it is the figure that matters. Write it down; it is your before number.

Also write down the free space the Mac reports, because that is what the prune is for:

$ diskutil info / | grep "Container Free Space"
$ df -h /

See what Docker says it can reclaim

Docker Desktop has to be running for these commands. Start it with open -a Docker and wait until docker info succeeds.

docker system df prints how much each kind of object uses and how much of it Docker thinks it could reclaim:

$ docker system df

On October 16 it showed 7 images, 1 of them active, 13.61GB in total with 4.213GB (30%) reclaimable. On October 19 it showed 2 images, 12.06GB, with 5.548GB (46%) reclaimable.

Docker has no dry-run option for the image prune that I found; its help text lists --all, --filter and --force only. To preview, list the images and the containers, including stopped ones, and compare them by hand:

$ docker images
$ docker ps -a

An image that no container in the second list uses is a candidate for docker image prune -a. An image that a stopped container uses is not.

Prune images with no container

Two commands look alike, and they remove different sets. According to docker image prune --help, -a removes all unused images, which is more than the dangling ones. Plain docker image prune removes only dangling images, meaning untagged ones, so a tagged image that no container uses stays unless you pass -a.

$ docker image prune -a

Without -f, Docker asks for confirmation first. On October 16 (run with -f) it removed the six images with no container and reported Total reclaimed space: 7.104GB. The images went from 13.61GB to 6.508GB. An image that a stopped container uses, that container and its volume stayed, because the container used the image.

I didn’t run docker volume prune or docker system prune, and this page doesn’t either. A volume holds an app’s data, and docker system df showed one local volume of 1.408GB that I wanted to keep.

Prune the build cache with –all

This section rests on my recollection of a run on October 15, not on a terminal transcript, so treat the numbers as my report. Plain docker builder prune reported 24.58kB reclaimed. After docker builder prune --all, Docker reported a total of 7GB, and docker system df showed the build cache at 0B. Docker’s reference for docker builder prune (opens in a new tab) describes --all as removing all unused build cache, not only the dangling part. On Docker Desktop 4.96.0 the command runs as docker buildx prune, and its --help describes --all as “Include internal/frontend images” instead. Check docker builder prune --help on your version before you run it. Free space read 44Gi before it and 43Gi after, with no record of how long after; given how late the space came back on October 16, that reading was probably taken too soon, but I can’t show it. I didn’t re-run this one, so I can’t tell you what the same commands report on your version.

$ docker builder prune --all

Wait before judging the result

Free space did not move right after the prune. On October 16, the reading straight after was unchanged at 66,071,195,648 bytes, and Docker.raw still read 15G. Five minutes later free space was 73,278,255,104 bytes (up 7.2 GB) and Docker.raw read 8.6G. At 15 minutes both were unchanged from the five-minute reading.

On October 19, the second run, the space came back within a minute. Free space rose from 80.63 GB to 83.62 GB by the one-minute reading, and Docker.raw read 14G at the start and 8.6G from the one-minute reading on. I took no readings inside that first minute, so I can’t say when it moved.

Docker’s documentation (opens in a new tab) says the same thing: “It might take a few minutes to reclaim space on the host.” A df taken straight after the prune makes it look as if nothing happened. Wait, then read both again:

$ du -h ~/Library/Containers/com.docker.docker/Data/vms/0/data/Docker.raw
$ diskutil info / | grep "Container Free Space"

Check the reclaimed figure against Docker.raw

Docker’s printed total and the earlier estimate differed in one run and matched in the other:

On October 16 the printed 7.104GB came close to the 7.2 GB of free space the Mac gained. On October 19 it didn’t: Docker.raw shrank by about 5.4G (about 5.8 GB) while free space rose about 3.0 GB. Other writes and frees on the Mac run at the same time, so free space moves less, or more, than the file does. Treat Docker.raw from du, and the free space after the wait, as the measure, and the printed total as approximate.

The listed image sizes also add up to more than the estimate. On October 16 the unused images’ listed sizes added to about 10 GB while Docker estimated 4.213GB reclaimable. Shared layers, which Docker stores once, are the likely cause; I did not check the SHARED SIZE column of docker system df -v.

Do this with a coding agent

Paste this prompt into your own local coding agent. It measures and reports, and it asks before anything is removed:

Investigate Docker Desktop's disk use on this Mac. Measure and report only;
change nothing yet.

0. Docker Desktop has to be running. If it is not, start it with
   open -a Docker and wait until docker info succeeds.
1. Read Docker.raw two ways: ls -lh and du -h on
   ~/Library/Containers/com.docker.docker/Data/vms/0/data/Docker.raw.
   Explain that ls shows the sparse maximum and du the real size.
2. Report free space with diskutil info / (Container Free Space) and df -h /.
3. Run docker system df and docker system df -v. Report each category's total
   and reclaimable figure.
4. List images that no container uses (compare docker images with docker ps -a,
   including stopped containers), with each one's size. List the build cache
   and its size. These two are the only removal candidates.
5. Report every volume with its size. Never propose removing a volume, and do
   not run docker volume prune or docker system prune.

Then stop and wait for my confirmation. For images, remove only the ones I
name, with docker image rm <image>. Run docker image prune -a -f only if I
confirm removing every image on the list. For the build cache, run
docker builder prune --all -f only after I confirm.

After the prunes, wait a few minutes. The space can take that long to return.
Then read du on Docker.raw and the free space again with the same commands, and
compare the change against the total reclaimed space Docker printed. Say how far
apart they are. Do not conclude the prune failed from a reading taken right
after it.

Common failures

Space doesn’t come back after you quit and reopen the app

After the prune, Docker.raw read 8.6G before and after I quit and reopened Docker Desktop, on October 16 and again on October 19. Free space read 75.5 GB after the first reopening, but Docker.raw did not change, so that rise came from something else on the Mac.

Space doesn’t come back after you update the app

I updated Docker Desktop on October 16 and, with docker desktop update, on October 20, and Docker.raw did not shrink either time: on October 20 it read 9,020,776 KB before and 9,020,796 KB after, 20 KB more. That is what I ran, on those versions; I make no claim about other releases.

$ docker desktop update --check-only
$ docker desktop update --quiet