sha256sum on Mac: Built In, but -c Can Pass on Nothing

If you're on macOS 15 or later, you already have sha256sum. It lives at /sbin/sha256sum, sha256sum --version prints sha256sum (Darwin) 1.0, and sha256sum file.tar.gz gives the same <hash> <name> line GNU gives. Nothing to install for that part.

Check mode is where it breaks. I ran the Mac binary and GNU coreutils 9.12 through the same inputs on this Mac mini (macOS 26.4.1). Two results matter. A checksum list piped in without a - gets a usage error. And sha256sum -c exits 0 when it checked nothing, for example when the "checksum file" is a saved 404 page. GNU exits 1 on both.

Where it came from

Apple's sha256sum is FreeBSD's md5 program. The same 136,576-byte program sits in /sbin under twelve names: md5, sha1, sha224, sha256, sha384, sha512, and each of those with sum on the end. When the name ends in sum, it switches to a GNU-style mode. FreeBSD added that mode in 2021.

Apple publishes the source in text_cmds, so I checked which macOS first shipped it. Every macOS 14 tag in Apple's distribution-macOS repo points at text_cmds-165, which has no GNU mode. macOS 15.0 through 15.3 point at text_cmds-190.0.1, the first version with it, and macOS 26.0 is on text_cmds-197. So on Sonoma and earlier, sha256sum: command not found is still the answer, and shasum -a 256 is the built-in you use.

Plain hashing matched GNU byte for byte in every form I tried: file arguments, - for stdin, -b, --tag, -z. Check mode is different.

Trap 1: a piped list gets a usage error

This is the line in half the install scripts on GitHub:

$ echo "5891b5b5...f6be03  a.txt" | sha256sum -c
usage: sha256sum [-bctwz] [files ...]
$ echo $?
1

GNU reads the checksum list from stdin when -c has no file argument. The Mac version doesn't. In Apple's md5.c, check mode with no arguments goes straight to usage(), and FreeBSD's current source has the same two lines. That contradicts the man page shipped on the same Mac, which says stdin is used "if no files are listed on the command line."

The fix is one character. sha256sum -c - works, and so do /dev/stdin and <(...). I tested all three.

Here is the part most write-ups get wrong. --check, --status, --quiet, --strict, --warn and --ignore-missing all work on the Mac when you give them a file. The usage error prints the short option list [-bctwz], which makes it look like the long options are missing. They aren't. What's missing is stdin.

Trap 2: exit 0 with nothing checked

This one worries me more, because nothing fails. I gave both tools checksum files that contain no usable line for the file being checked:

With the 404 page, the Mac prints WARNING: 3 lines are improperly formatted to stderr and exits 0. Add --status, which is what scripts use, and it prints nothing and exits 0. GNU stops with no properly formatted checksum lines found. The --ignore-missing row is the same idea. The file name in the list doesn't match what you downloaded, nothing gets verified, and GNU 9.12 says no file was verified and exits 1. The Mac exits 0.

The first fix people reach for is also open to this. grep ' app.tar.gz$' SHA256SUMS | sha256sum -c - gets past the usage error. But if the grep matches nothing, the Mac gets an empty list and exits 0. GNU and shasum -a 256 -c both exit 1 on the same empty input. --strict helps with the 404 page, where malformed lines become exit 1, but not with the empty file, which still exits 0. And the grep's own failure is hidden by the pipe unless you set pipefail, the problem in bash pipe exit codes.

Two smaller differences from the same run:

• Windows line endings. A SHA256SUMS file with CRLF fails on the Mac with a.txt\r: No such file or directory. The source strips only \n. GNU accepts it. The built-in shasum fails on it too, so there's no fallback on the Mac for this one.
• Escaped names. GNU writes a leading \ on lines for names that contain a backslash or newline. The Mac counts those lines as malformed, which brings back trap 2: exit 0, nothing checked.

291 GitHub threads, 46 of them real

I searched GitHub issues and PRs for the exact string "usage: sha256sum [-bctwz]" in titles, bodies and comments and fetched all 291 results. 245 trace back to one fix, aqua-installer #750, "take inputs from stdin for sha256sum," merged 2025-01-21. That's the fix PR itself plus 244 bot PRs (217 from Renovate, 19 from Dependabot) that quote its release note, 182 of them opened in January 2025. So most of the raw count reflects how widely aqua-installer is used, not how many people hit the bug.

That leaves 46 independent threads, 27 PRs and 19 issues. By year: 1 in 2023, 5 in 2024, 14 in 2025, 26 so far in 2026. The earliest Mac one is apache/maven-wrapper #155 from 2024-09-19, titled "Fails to validate checksums on MacOS Sequoia." It diagnoses the problem correctly: add the -.

I read the 46 bodies for the stated cause. 23 give one. 9 name stdin, and 3 of those also blame the flags. 14 blame the flags alone: "does not support --check or --status," "rejects GNU long options," or "a BSD variant without check mode." agent-nexus #33 is a typical one. As shown above, those flags work on the Mac. Every thread I opened that shows the actual failing line is piping the list in. famclaw #215 writes the command as sha256sum -c checksums.txt, but the call in its scripts/update.sh is a bare sha256sum -c with the list coming in on a pipe. The flag-based fixes still work, because they switch to shasum -a 256 or compare digests in shell and stop piping into -c. But the reasoning left in these repos is wrong, and the next person who reads it will avoid flags that work.

One more pattern from the threads. Several scripts already had a shasum fallback behind if command -v sha256sum. On macOS 15 that check succeeds, so the fallback never runs and the Mac binary gets the GNU call. The scripts were written for Macs where sha256sum didn't exist, the same situation as timeout: command not found on Mac, and then macOS added the command.

What I use now

Don't depend on check mode. Look up the expected hash yourself, fail if you can't find it, then compare:

#!/bin/sh
# verify.sh <file> <sums-file>
f=$1; sums=$2
expected=$(awk -v f="$f" '{ sub(/\r$/, "") } $2 == f || $2 == "*" f { print tolower($1); exit }' "$sums")
[ -n "$expected" ] || { echo "no checksum line for $f in $sums" >&2; exit 1; }
if command -v sha256sum >/dev/null 2>&1; then actual=$(sha256sum < "$f")
else actual=$(shasum -a 256 < "$f"); fi
actual=${actual%% *}
[ "$actual" = "$expected" ] || { echo "MISMATCH $f" >&2; exit 1; }
echo "OK $f"

I ran it against the same inputs as the chart, with the Mac sha256sum, with GNU first in PATH, and with PATH=/usr/bin:/bin. That last one has no /sbin, so it falls through to shasum. Valid list, CRLF list and uppercase hex: OK. Wrong hash: MISMATCH, exit 1. 404 page, empty file and BSD --tag format: "no checksum line," exit 1. It doesn't handle file names with spaces. Those also fail with exit 1, which is the side you want to fail on.

If you'd rather keep -c, three rules cover everything above: always pass a file or -, never pipe an empty result into it, and on a Mac treat exit 0 as meaning nothing was mismatched, not that something was checked. If you want GNU behavior outright, brew install coreutils installs gsha256sum without shadowing /sbin/sha256sum.

This is the same family as stat: illegal option -- c and date: illegal option on Mac. The difference is that stat and date always existed on macOS, and sha256sum is recent enough that scripts assuming it's missing are now wrong too.

Sources: every exit code and message above was run on 2026-09-30 on a Mac mini (macOS 26.4.1, build 25E253) against /sbin/sha256sum, /usr/bin/shasum, and gsha256sum from GNU coreutils 9.12 (Homebrew), which stood in for Linux. The macOS version mapping comes from the text_cmds submodule pointer in Apple's apple-oss-distributions/distribution-macOS tags macos-140 to macos-260. The source lines are from text_cmds-197 and FreeBSD main. GNU behavior is documented in the coreutils md5sum manual. The GitHub figures come from gh api search/issues for the quoted string, with all 291 results fetched the same day. Bots were separated by account type, and the cause classification is my own reading of each issue or PR body.