GuidesDocker Storage Guide

Why Docker.raw looks huge on your Mac (and how to get the space back)

You open Finder or a disk map and there it is: Docker.raw, listed at 64 GB, 1 TB, or close to the size of your whole drive. Sometimes that number is misleading. Sometimes Docker really is holding tens of gigabytes of old images and build cache. The first job is to find out which one you have, because the fixes are very different, and the most drastic fix wipes every container, image and volume.

This guide covers what the file is, how to read its real size, and a cleanup order where the early mistakes are cheap. Every step uses Docker's own commands and settings, so you don't need to install anything. If Docker is only part of a large system data number, the Mac system data guide covers the rest.

What Docker.raw is

Containers need a Linux kernel, so Docker Desktop on a Mac runs a small Linux virtual machine. Docker's Mac FAQ says it keeps Linux containers and images in "a single, large 'disk image' file" on your Mac. Every image, container, volume and bit of build cache lives inside it. The default path is:

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

If you changed it, Docker Desktop shows the current path under Settings → Resources → Advanced → Disk image location. Docker's docs say not to move the file in Finder, because Docker Desktop can lose track of it. Use Browse in that setting instead.

Storage settings has no category for a Linux VM's disk. Apple defines System Data as files that don't fall into the other categories, so that is usually where Docker.raw ends up.

Why Finder shows 64 GB or 1 TB

Docker.raw is a sparse file. It has a logical size, which is the most it is allowed to grow to, and an on-disk size, which is the blocks it actually uses. On APFS the unused part takes no space. Finder's size column, ls -l and plenty of cleaner apps show the logical size.

That cap has grown over the years. A Docker engineer described 64 GB as the default back in 2018, which is why so many old threads mention a 64 GB file. Docker Desktop 4.37 made 1 TB the default limit for new installs. Since 4.42, a fresh install or a reset to defaults sets the limit to the size of your physical disk. So a nearly empty Docker.raw can look as big as the drive it sits on.

When a user reported a 64 GB file in docker/for-mac issue #2297, a Docker engineer closed it as working as expected: ls -l shows the file's size, not the sectors the filesystem has actually allocated.

There is one case where the big number is real. Migration Assistant does not preserve sparse files. OrbStack's FAQ warns about this for its own disk image, and a commenter on the same Docker issue reported Migration Assistant copying the full 64 GB to a new Mac.

How much space it really uses

Ask macOS for both numbers. These commands only read sizes:

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

ls -lh prints the cap. du -h prints what the file takes on disk. Docker's FAQ uses ls -klsh Docker.raw for the same check: the first number in that output is the real size in kilobytes. In Finder, Get Info shows both, as a byte count followed by a figure marked "on disk". Docker Desktop shows the same split under Settings → Resources → Advanced.

If du reports a few gigabytes, Docker isn't your space problem and you can stop here.

If it's large, look inside before deleting anything:

docker system df docker system df -v

The first command lists images, containers, local volumes and build cache, each with a RECLAIMABLE column. The -v version breaks that down by image, container and volume. For build cache, docker buildx du shows each cache record for the current builder.

One check before you prune: make sure the docker command is talking to Docker Desktop. OrbStack and Colima add their own Docker contexts, and Colima makes itself the default when it starts. A prune against the wrong context cleans the wrong VM and leaves Docker.raw alone.

docker context ls docker context use desktop-linux

A cleanup order, cheapest mistakes first

Work down the list. Re-run docker system df and du -h Docker.raw as you go, and stop once you have enough room.

1. Stopped containers

docker container prune

Docker doesn't remove a stopped container unless you started it with --rm, and its writable layer still takes space. Anything a container wrote outside a volume goes with it.

2. Images

docker image prune docker image prune -a

The first removes dangling images, which are untagged and not used by any container. The second removes every image that no container uses, tagged or not. The cost is a re-pull or rebuild the next time you need one. To keep recent images, add a filter such as --filter "until=240h".

3. Build cache

If you build images on this Mac, this is often the biggest line in docker system df.

docker builder prune docker builder prune -a

Without -a it removes dangling cache. With -a it removes all unused build cache. Your next build is slower, and that's the whole cost.

If you've created extra builders with buildx, each one keeps its own cache. List them with docker buildx ls and prune one with docker buildx prune --builder <name>. Settings → Builders in Docker Desktop shows disk usage for each active builder.

BuildKit also trims its cache on its own. Docker's docs give Docker Desktop's default builder a defaultKeepStorage of 20GB, set in Settings → Docker Engine. Lower it if you build a lot on a small disk.

The shortcut: docker system prune

docker system prune

This removes stopped containers, unused networks, dangling images and unused build cache in one go, after it lists what it will remove and asks you to confirm. Add -a to include every unused image. It leaves volumes alone unless you add --volumes, and even then it only removes anonymous ones.

4. Volumes, last and by hand

Volumes are where databases and other container data live between runs. Docker's docs say volumes "are never removed automatically, because to do so could destroy data." The volume behind a local Postgres or MySQL may hold the only copy of that data.

docker volume ls docker system df -v docker volume rm <name>

Remove named volumes one at a time once you know what each one holds. docker volume prune only removes anonymous volumes that no container uses. docker volume prune -a also removes unused named volumes, and it's the command on this page to be most careful with. To keep a volume's contents, Docker's storage docs show how to back it up to a tar file first.

When Docker.raw doesn't shrink after a prune

Docker's FAQ says it "might take a few minutes to reclaim space on the host," and that space is freed when images are deleted, not when files are deleted inside running containers. Docker Desktop 4.20 sped up reclaiming space when files are deleted in containers. Give it a few minutes, then run du -h Docker.raw again.

The FAQ also offers a command to force it:

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

On Apple silicon, don't rely on it. The image on Docker Hub is amd64 only and was last pushed in 2019, and a pull request to Docker's docs says it doesn't work on Apple silicon.

The options that wipe everything

These make Docker.raw small in one step by throwing away what's in it. Back up first: push images you built to a registry or save them with docker image save -o images.tar <image>, and back up any volume you care about.

Lower the Disk usage limit: It's in Settings → Resources → Advanced. Docker's FAQ still calls it Disk image size, and some older versions showed Virtual disk limit. The FAQ says that when you reduce the maximum size, "the current disk image file is deleted, and therefore, all containers and images are lost." The confirmation dialog says volumes go too. Some guides claim a smaller limit keeps data that fits. Docker's docs say it doesn't.

Clean up data: Open Troubleshoot from the Docker menu bar icon or the question mark at the top right of the Dashboard. Docker's docs say this disk image reset "destroys all Docker containers and images local to the machine, preserving all settings." Older versions labeled it Clean / Purge data.

Move it instead: If you need the room but can't lose the data, Settings → Resources → Advanced → Disk image location moves Docker.raw to a bigger drive.

What is safe and what you lose

WhatHowWhat you lose
Stopped containersdocker container pruneFiles written inside them, outside volumes
Dangling imagesdocker image pruneUntagged layers nothing uses
Unused imagesdocker image prune -aA re-pull or rebuild
Build cachedocker builder prune -aA slower next build
Anonymous volumesdocker volume pruneWhatever was in them
Named volumesdocker volume rm <name>Possibly the only copy of a database
The whole disk imageDisk usage limit, Clean up dataAll of the above at once

If you use OrbStack or Colima

OrbStack stores Docker data in a sparse data.img file. Its FAQ says the file shows as 8 TB, only takes what you use, and shrinks on its own when you delete data. To check the real size:

du -h ~/Library/Group\ Containers/HUAQ24HBR6.dev.orbstack/data/data.img

Colima's FAQ says space freed inside its VM is released on startup from v0.5.0, or right away with colima ssh -- sudo fstrim -a. Its disk can only be made bigger after creation. colima prune only empties Colima's cache of downloaded assets, not your Docker data.

The prune commands above work in both once the right context is active.

If you moved off Docker Desktop, its data may still be there. Docker's uninstall docs say the uninstall command can leave ~/Library/Containers/com.docker.docker behind, and that you can remove it later once Terminal has Full Disk Access. Measure it first with du -sh. Docker's docs also list ~/.docker as a leftover, but the docker command still uses that folder with Colima or OrbStack (Colima's FAQ installs the buildx plugin into ~/.docker/cli-plugins), so leave it if you still run Docker another way.

Where a careful cleaner fits

Docker's own commands are the right tool for what's inside Docker.raw. A Mac cleaner can't see images or volumes. It sees one big file.

Purge treats it that way. Its Dev Tools list shows Docker Desktop's folder, ~/Library/Containers/com.docker.docker, as a single row marked Check First, so one-click and scheduled cleaning never pick it up. The size on that row comes from du, so it's the space used on disk, not the cap. The row's explanation tells you to run docker system prune against the desktop-linux context instead, and to quit Docker Desktop before deleting the folder. If you select it anyway, the whole folder goes to the Trash with every image, container and volume in it, and the space only comes back when you empty the Trash.

Purge doesn't run Docker commands, and it doesn't touch ~/.docker, OrbStack or Colima. Where it helps is the rest of a dev Mac: Xcode DerivedData (see the Xcode storage guide), Homebrew, npm, pnpm and other package caches. It's free and MIT-licensed, so you can read the code on GitHub.

Download PurgeView on GitHub

Sources