How can I get accurate information about disk space used/available in Big Sur via the command line?

Question

Summary:

I would like to be able to tell how much disk space I have used and how much I have available (in GB) in Big Sur in a simple format suitable for parsing in a shell script or similar.

Details

Finder reports that my internal SSD is 995 GB and has 568 GB free.

Simple math tells us that means I have used 427 GB.

So… how can I get 568 GB and/or 427 GB from the command line?

Hint: The answer is not df

If I do df -H / I will get this result (truncated for readability and to just the parts of the output we care about):

Filesystem       Size   Used  Avail Capacity
/dev/disk3s1s1   995G    15G   528G     3%

15G might be how much the read-only volume takes up, but the “available” amount is off by 40G.

Of course we know that there’s now a separate ‘Data’ volume. So let’s check that using df -H /System/Volumes/Data:

Filesystem     Size   Used  Avail Capacity
/dev/disk3s5   995G   445G   528G    46%

445G used is relatively close to the actual amount of 427G but if you add up the “Used” (445G) and “Available” (528G) you get 973G.

There must be some way to do it…

I have noticed that other apps such as iStat Menus and MakeMKV are both able to display accurate information about the remaining disk space. So it’s not as if the system is incapable of revealing this information.

If there is another tool besides df that can do this, please let me know.

Bonus points if it comes standard with macOS (bash, zsh, python, ruby, whatever), but if it can be installed via brew or similar, I’ll take it.

What I’m asking for seems very simple, but I can’t figure out how to do it.

p.s. - yes, I’m aware of macOS’ features about “purgeable space” and all that. Not interested. I just want to be able to get the same numbers shown in Finder, iStat Menus, etc. from the command line.

Answer 1

diskutil info /dev/disk3s1s1 seems to do the trick for me:

Container Total Space:     994.7 GB (994662584320 Bytes) (exactly 1942700360 512-Byte-Units)
Container Free Space:      635.1 GB (635058384896 Bytes) (exactly 1240348408 512-Byte-Units)

(other output snipped)

My output from df -H:

/dev/disk3s1s1 995G    15G   634G     3%    568975  9712932825    0%   /
/dev/disk3s5   995G   335G   634G    35%   1363090  9712138710    0%   /System/Volumes/Data

Answer 2

AppleScript can get the free space of a disk, which gives the same number as the Finder.

Open Script Editor and save the following script as ~/Library/Scripts/Free Space.scpt:

tell the application "Finder"
    -- Change this if your drive is not called "Macintosh HD"
    set drive_name to "Macintosh HD"
    
    set free_bytes to (free space of disk drive_name)
    set free_Gbytes to (free_bytes / (1024 * 1024 * 0.1024) div 100) / 100
    return drive_name & " has " & free_Gbytes & " GB free"
end tell

Then run

osascript ~/Library/Scripts/Free\ Space.scpt

The first time you run it it will popup a dialog asking you if it's OK for osascript to control the Finder.

Note that my AppleScript skills are pretty terrible, so any suggestions on how to improve the above script are welcome.

Example output

Macintosh HD has 35.85 GB free