Understanding the du command (and why dux exists)

What du does

du stands for disk usage. It walks a folder, adds up the space each file takes on disk, and prints a total per folder. It first appeared in the very first version of Unix, around 1971, and every Mac ships with it.

The key word is “on disk”. du counts the blocks a file occupies, not the number of bytes in it. A 10 byte text file still takes a whole block, and a compressed or sparse file can take far less than its length. That is usually what you want when you are looking for space.

Open Terminal and try it on your Downloads folder:

~ % du -sh ~/Downloads
6.0G	/Users/you/Downloads

-s asks for one summary line instead of a line for every subfolder, and -h prints human readable sizes instead of 512 byte blocks.

The commands worth remembering

The largest folders, one level deep

This is the one most people end up using every week:

~ % du -hd 1 ~ 2>/dev/null | sort -h | tail -8
4.1G	/Users/you/Pictures
6.0G	/Users/you/Downloads
 12G	/Users/you/Movies
 28G	/Users/you/Projects
 31G	/Users/you/Documents
 74G	/Users/you/Library
162G	/Users/you

• -d 1 limits the output to one level below the folder you give.
• sort -h sorts human readable sizes correctly, so 900M comes before 2G.
• tail -8 keeps the largest entries.
• 2>/dev/null hides permission errors, more on those below.

From there, run the same command on the largest folder, and repeat. That is how most people find their space, one level at a time.

Only folders above a size

-t sets a threshold, so small folders stay out of the list:

~ % du -hd 2 -t 1G ~/Library 2>/dev/null | sort -h

Several items with a total

-c adds a grand total at the end, which is handy with wildcards:

~ % du -shc ~/Movies/*.mov

Hidden folders too

A shell wildcard like * skips names that start with a dot, and that is where many developer tools keep their data (~/.npm, ~/.cargo, ~/.docker). Include them explicitly:

~ % du -sh ~/.[!.]* 2>/dev/null | sort -h | tail -5

Stay on one disk

-x stops du from crossing into other volumes, such as an external drive or a mounted disk image inside the folder you scan.

macOS du is not Linux du

Your Mac uses the BSD version of du, not the GNU version found on most Linux systems. Commands copied from a Linux tutorial often fail with “illegal option”. The common translations:

• --max-depth=1 on Linux is -d 1 on macOS.
• --apparent-size on Linux is -A on macOS (shows the file length instead of the space on disk; check man du if your version lacks it).
• --exclude=PATTERN on Linux is -I PATTERN on macOS.
• -h on both uses powers of 1024. macOS also accepts --si for powers of 1000, which matches the sizes Finder shows.

If you prefer the GNU flags, Homebrew’s coreutils package installs GNU du as gdu.

Why du says “Operation not permitted”

Run du on your Library folder and you will see lines like:

~ % du -sh ~/Library
du: /Users/you/Library/Mail: Operation not permitted
du: /Users/you/Library/Safari: Operation not permitted
 74G	/Users/you/Library

macOS protects folders such as Mail, Messages, Safari and other apps' containers. Terminal can only read them when it has Full Disk Access in System Settings > Privacy & Security. Without it, du skips those folders, so the total is lower than the truth. That is worth knowing: a du total on ~/Library is a minimum, not the real size.

Where du gets it wrong on a modern Mac

du was designed long before APFS, iCloud Drive and Time Machine snapshots. On a Mac in 2026, a few of its numbers mislead.

APFS clones count twice

When you duplicate a file in Finder, APFS makes a clone: two files that share the same blocks until one of them changes. du sees two full files and counts both. A folder with many clones can look gigabytes larger than the space it really uses, and deleting a clone frees almost nothing.

Snapshots are invisible

Time Machine local snapshots and other APFS snapshots keep deleted files on disk until the snapshot goes. du only sees files that exist now, so it cannot explain space held by a snapshot. This is part of why deleting a large file sometimes frees nothing right away.

Cloud files show what is local

Files in iCloud Drive or another cloud folder that are online only take almost no space, and du correctly shows a small number. But it cannot tell you how large those files are in the cloud, or which ones are downloaded.

No idea what is safe

du tells you that a folder is large. It cannot tell you whether it is a cache that rebuilds, a build folder you can recreate, or the only copy of your photo library. That part is up to you.

Why it is called dux

dux stands for Disk Usage eXtended, and the name is a nod to du. It started from the same question du -hd 1 | sort -h answers, “where did my space go?”, and then tries to answer the next ones: which of these gigabytes rebuild on their own, which are clones that free nothing, which are cloud files, and what happens if they go.

If you are comfortable in Terminal, du remains a great first look. dux also has a command line tool, and dux scan gives a similar summary of the largest folders, measured the same way as in the app:

~ % dux scan ~/Projects --top 10
~ % dux suggest ~

dux suggest lists cleanups with a safety level and the rule behind each one, and changes nothing.