du Command on Mac: A Practical Tutorial for Checking Disk Usage (2026)

If your Mac keeps telling you disk space is running low, the du command on Mac is one of the most direct ways to find out exactly where the bytes are hiding. This tutorial walks you through every practical form of du you'll actually need — from a simple one-folder check to a sorted list of your twenty heaviest directories — and flags the APFS-specific gotchas that trip up even experienced developers.

What du Does (and What It Doesn't)

du stands for disk usage. It recurses through a directory tree and reports how much space the files inside actually occupy on disk. It does not report free space — that's df's job (more on that below). On macOS, du is the BSD variant, so a couple of flags behave slightly differently from GNU/Linux.

Basic Syntax

du [options] [path...]

Run without arguments, du recurses from your current directory and prints a line for every subdirectory it finds — which is usually too much noise. The flags below cut through that.

du -sh: The One Flag You'll Use Most

The most common invocation is du -sh, where:

• -s — summarize: print only one total for each argument instead of every subdirectory
• -h — human-readable: show sizes as K, M, G instead of 512-byte blocks

# Size of your entire home directory
du -sh ~

# Size of a specific folder
du -sh ~/Library/Caches

# Size of several folders at once
du -sh ~/Downloads ~/Movies ~/Library/Application\ Support

Finding Your Largest Directories

The real power comes from combining du with sort. The following one-liner lists the 20 largest immediate subdirectories of your home folder:

du -sh ~/* | sort -rh | head -20

Breaking it down:

• du -sh ~/* — summarizes every item directly inside ~
• sort -rh — sorts in reverse (-r) by human-readable size (-h), so 10G sorts above 500M
• head -20 — keeps only the top 20 results

To go deeper — say, find the biggest folders anywhere inside ~/Library — use -d 2 to limit recursion depth:

du -hd 2 ~/Library | sort -rh | head -20

Scanning System Directories with sudo

Many folders outside your home directory are protected. Without sudo, du silently skips them and your totals will be wrong:

# Scan /private/var (logs, tmp) — requires sudo
sudo du -sh /private/var/*  | sort -rh | head -10

# Whole-disk summary (expect it to be slow)
sudo du -hd 1 / | sort -rh | head -20

The whole-disk scan can take several minutes on an HDD or on a large SSD. For SSDs it's usually under a minute, but don't Ctrl-C it mid-run or you'll get partial output.

du vs df: Understanding the Difference

# Check free space on all mounted volumes
df -h

# Check only your main APFS volume
df -h /

You'll often use both together: df tells you how much headroom you have; du tells you who ate it.

APFS Gotchas: Why du Numbers Sometimes Lie

APFS introduces two behaviors that can make du output misleading on macOS 12 through 26.

1. Local Snapshots

Time Machine on APFS stores local snapshots directly on your internal drive. These snapshots can consume gigabytes, but du / won't show them as files because they live in the snapshot store, not in the directory tree. The Finder and "About This Mac" storage view include them; du doesn't.

To see how much space your local snapshots occupy:

tmutil listlocalsnapshots /
tmutil thinlocalsnapshots / 9999999999999 4   # force-thin to reclaim space (use with caution)

2. Purgeable Space

APFS marks some blocks as purgeable — iCloud-backed files that macOS can evict on demand, cached App Store content, and optimized storage items. du counts these as used. df counts them as used too. The Finder's "Available" figure in Get Info subtracts purgeable space from used, so it can appear more optimistic than df -h.

This is why deleting files sometimes doesn't free as much space as you expect: the bytes reported by du were already earmarked as purgeable and macOS wasn't going to keep them forever anyway.

If you want an accurate read on genuinely used vs. genuinely free space on APFS — including purgeable blocks — you need a tool that queries the APFS volume attributes directly. Crumb reads these attributes natively and shows you how much is purgeable vs. truly occupied, which is something du and df alone can't surface clearly.

Practical Recipes

Find large caches you might be able to clear

du -sh ~/Library/Caches/*  | sort -rh | head -20
du -sh ~/Library/Application\ Support/* | sort -rh | head -20

Check developer toolchain bloat

# Xcode derived data — often many gigabytes, safe to delete
du -sh ~/Library/Developer/Xcode/DerivedData

# iOS device support files (old device simulators)
du -sh ~/Library/Developer/Xcode/iOS\ DeviceSupport/*

# Homebrew cache
du -sh "$(brew --cache)"

# npm global cache
du -sh ~/.npm/_cacache

# Docker images (if Docker Desktop is installed)
du -sh ~/Library/Containers/com.docker.docker/Data/vms

Full top-20 one-liner for any starting point

sudo du -hd 3 /Users | sort -rh | head -20

Adjust the depth (-d 3) and starting path to taste.

What Is Safe to Delete — and What Isn't

Generally safe to delete:

• ~/Library/Caches/* — app caches rebuild themselves; expect some apps to launch more slowly the first time
• ~/Library/Developer/Xcode/DerivedData — Xcode rebuilds these on next build
• ~/Library/Developer/Xcode/iOS DeviceSupport — only needed for debugging on that specific iOS version
• Old .dmg installers in Downloads
• Homebrew cache (brew cleanup)

Do NOT delete without understanding what you're removing:

• ~/Library/Application Support/ — contains app data, save files, preferences, and license information; deleting the wrong subfolder can mean lost data
• /System/Library/ — protected by SIP; you shouldn't be able to delete these anyway, but don't try
• ~/Library/Mail/, ~/Library/Messages/ — your email and iMessage history
• Any folder inside another user's home directory — use cross-user cleaning tools only if you understand what you're doing

If you're ever unsure, the Crumb app's "Is this safe to delete?" AI can explain any folder and its risk before you commit. Cleaning is permanent — there's no undo once you've emptied a directory from the Terminal.

When the Terminal Isn't the Right Tool

du is powerful but it has blind spots: APFS purgeable blocks, local Time Machine snapshots, iCloud-optimized storage, and system-protected paths all require either extra flags or a deeper API call than du provides. For a complete picture — or for moments when you'd rather click than type — download Crumb for a disk treemap that accounts for APFS semantics and lets you browse, inspect, and remove large items in a single window.

Conclusion

The du command on Mac is an indispensable first step for diagnosing disk usage: fast, scriptable, and accurate for user-space files. Pair du -sh for quick spot checks with du -hd N | sort -rh | head -20 for ranked lists, and keep the APFS snapshot and purgeable caveats in mind when numbers don't add up. For the parts of disk analysis that fall outside what du can see, a purpose-built tool fills in the gaps.