My Mac was down to 7.3 GB of free space last week, so I went looking for what was eating it. The biggest file on the machine was easy to spot: a Docker.raw file with a size of 1 TB.

My SSD is 228 GB.

If you searched "Docker.raw 1TB" because your Mac showed you the same thing, you probably had the same moment. A file four times bigger than the disk it lives on, and your first instinct is to delete it.

Don't. Here's the output that changed my mind:

$ cd ~/Library/Containers/com.docker.docker/Data/vms/0/data $ ls -klsh Docker.raw 1844848 -rw-r--r--@ 1 priyanshutiwari staff 1.0T Oct 30 07:48 Docker.raw

Two sizes on one line. The 1.0T near the end is what the file claims. The 1844848 at the start is what it actually uses, in kilobytes. That's about 1.8 GB.

So the scariest file on my Mac was innocent. This is what I learned chasing it, and where my space really went.

The one idea: a file has two sizes

Most of us think of a file's size as one number. It's really two:

  • Logical size: how long the file says it is.
  • Physical size: how much of the disk it actually occupies.

For nearly every file you own, those match, give or take. A sparse file is one where they don't. The file says "I'm 1 TB long", but the filesystem only stores the parts that have been written. The empty stretches aren't stored anywhere. They just read back as zeros.

Think of a 1,000-page notebook where only the 2 pages you wrote on physically exist. The page numbers still go up to 1,000.

macOS will show you both numbers for my Docker.raw if you ask it directly:

$ mdls -name kMDItemFSSize -name kMDItemPhysicalSize Docker.raw kMDItemFSSize = 1099511627776 kMDItemPhysicalSize = 1889124352

That's 1,099,511,627,776 bytes claimed and 1,889,124,352 bytes used. Under 0.2% of what it says it is.

Make your own fake 10 GB file

I didn't fully believe this until I made one. It takes 10 seconds and costs you no space. Run it in a temp folder:

cd "$(mktemp -d)" dd if=/dev/zero of=sparse.img bs=1 count=0 seek=10g ls -lh sparse.img # says 10G du -h sparse.img # says 0B

On my Mac, ls said 10G and du said 0B. A 10 GB file on a disk with 5.9 GB free, using nothing.

Then I wrote 2 bytes into the middle of it, 5 GB in:

printf hi | dd of=sparse.img bs=1 seek=5368709120 conv=notrunc du -h sparse.img # says 16K

16K. The filesystem stored one small block for those 2 bytes and still didn't bother with the other 10 GB. A plain cp on the same disk kept the copy sparse too, at 0B.

That's the whole trick. ls reports the claim. du reports the disk. When they disagree, believe du.

One limit on what I tested: all of this was on APFS, on one Mac. I didn't try zipping the file, uploading it or copying it to another drive, so don't assume it stays small on those trips.

Why Docker does this on a Mac

Containers need Linux, and a Mac isn't Linux. So Docker Desktop runs a Linux VM and, as its Mac FAQ puts it, keeps your containers and images in one large disk image file instead of a folder like /var/lib/docker.

The VM wants to see a big disk. Your Mac doesn't want to give up that space on day one. Sparse storage solves both: the VM sees the full size, and the Mac only pays for what's been written.

The same FAQ warns about the exact thing that scared me. Many tools report the maximum size of that file, not the size it's really using.

So the 1 TB is a ceiling, not a bill. That also means it isn't a reservation. With a 1 TB ceiling on a 228 GB disk, nothing in that number stops Docker from filling my drive first. The ceiling tells you nothing about your free space. Only du does.

When Docker really is the problem

Sometimes the physical size is the big one. A real image-heavy setup can use tens of GB. Check the physical number first, then use these, in this order.

1. See what's inside. With Docker running:

docker system df

This breaks usage down into images, containers, volumes and build cache.

2. Prune what's unused.

docker system prune

Docker's FAQ says this removes stopped containers, unused networks, dangling images and build cache, and that it can take a few minutes for the space to come back on the Mac. So don't panic if du doesn't drop right away. Read the confirmation prompt before you say yes, especially if a stopped container holds something you care about.

3. Know what doesn't help. The FAQ says deleting files inside a running container doesn't free the space automatically. It lists a command to trigger that:

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

4. Treat the disk limit as a last resort. The setting lives under Settings > Resources > Advanced, called Disk usage limit on the current settings page. The FAQ, which calls it the disk image size, warns that reducing it deletes the current disk image, and all your containers and images go with it.

And two things not to do. Don't drag Docker.raw somewhere else in Finder, because the FAQ says Docker Desktop can lose track of it. Use the Browse option in settings. And don't delete it to "fix" a 1 TB reading, because you'd be wiping your local containers and images to recover whatever du says it was using. For me, that's 1.8 GB.

A note on what I ran: the ls, mdls, dd and du output above is from my Mac. I didn't run the prune commands for this piece, because with 1.8 GB in there I had nothing worth pruning. Those steps come from Docker's docs.

Where my space actually was

Once Docker was cleared, I had to find the real culprits. Measure the folders, not the file list:

du -xh -d 1 ~ 2>/dev/null | sort -h | tail -15

Because du counts physical size, a sparse file can't fool it. On my Mac the real weight was in two places: codes at 59 GB and Group Containers at 28 GB.

I'd spent my time staring at a 1 TB file using 1.8 GB. The actual problem was 87 GB sitting in two folders I never look at.

I got from 7.3 GB free to 17 GB, stopping before anything I couldn't get back. WhatsApp media, for one, is something to look through yourself, not bulk-delete.

And two days later, I was back down to 5.9 GB free. So the honest lesson isn't "I fixed it". It's that the number you stare at should be the right number.

Quick answers

Why is Docker.raw so big on my Mac?
It usually isn't. It's a sparse file, so tools like ls show the maximum size while the disk stores far less. Run ls -klsh Docker.raw or du -h Docker.raw to see the real number.

Why does Docker.raw say 1 TB?
1 TB is the ceiling Docker set for its Linux VM's disk, not what it's using. The VM sees the full size, and your Mac only stores what has been written.

Is Docker why my Mac's System Data is so big?
It can be part of it. Before deleting anything, check the physical size of Docker.raw with du, then measure your home folder the same way. Mine turned out to be 1.8 GB, and the real weight was elsewhere.

Where is Docker.raw on a Mac?
Docker's FAQ uses ~/Library/Containers/com.docker.docker/Data/vms/0/data/Docker.raw as its example, and mine is there too. Settings > Resources > Advanced shows the exact location for your install.

Can I delete Docker.raw?
You'll lose your local containers and images, so only do it if you're fine rebuilding them. Try docker system df and docker system prune first.

Why doesn't my disk space come back straight after pruning?
Docker's FAQ says it can take a few minutes for the Mac to get the space back.

What's the difference between ls and du?
ls -l shows how long a file claims to be. du shows how much disk it occupies. They only disagree in a big way on sparse files, and that's when du is the one to trust.

I write about what I run into while building things, usually at 4 am and usually on a full disk. If that's your kind of problem, follow me on X.