everyday mac tools

Verify a checksum on a Mac before you open a download

· 6 min read

To verify a checksum on a Mac, open Terminal, type shasum -a 256 followed by a space, drag the downloaded file into the window and press Return. Compare the 64 characters it prints with the SHA-256 value the publisher lists. If every character matches, the file on your disk is identical, byte for byte, to the one the publisher measured. If even one differs, do not open it.

What a checksum is

A checksum (also called a hash or a digest) is a short fingerprint calculated from every byte of a file. Change a single byte and the fingerprint changes completely. Publishers list one beside a download so you can confirm that what arrived is what they released: not cut short by a dropped connection, not altered by a mirror, not swapped somewhere along the way.

macOS ships with the tools to calculate one, so there is nothing to install.

Check a download with shasum

  1. Find the checksum on the publisher’s site. It is usually labelled SHA-256 or SHA256 and sits next to the download link, or in a separate file named something like SHA256SUMS.
  2. Open Terminal, in Applications, Utilities.
  3. Type shasum -a 256 with a space at the end. Do not press Return yet.
  4. Drag the downloaded file from Finder into the Terminal window. Terminal fills in the full path for you.
  5. Press Return.

The result is the hash, then the path:

shasum -a 256 ~/Downloads/installer.dmg
3a7bd3e2360a3d29eea436fcfb7e44c735d117c42d1c1835420b6b9942dd4f1b  /Users/you/Downloads/installer.dmg

A large file takes a few seconds, because every byte is read. Upper and lower case do not matter: the hash is a hexadecimal number, so 3A7B and 3a7b are the same value.

If the publisher lists a different algorithm, match it. shasum -a 512 gives SHA-512, shasum -a 1 gives SHA-1, and md5 followed by the path gives MD5. You can tell them apart by length: MD5 is 32 characters, SHA-1 is 40, SHA-256 is 64 and SHA-512 is 128.

Let the Mac do the comparing

Comparing 64 characters by eye is where this goes wrong. Most people check the first few and the last few, which is a weak test. Let shasum compare instead.

Move to the folder that holds the download, then pass it the published hash and the file name:

cd ~/Downloads
echo "PASTE_THE_PUBLISHED_HASH  installer.dmg" | shasum -a 256 -c

There are two spaces between the hash and the file name. The answer is plain: installer.dmg: OK or installer.dmg: FAILED.

If the publisher provides a checksum file, save it in the same folder as the download and run:

shasum -a 256 -c SHA256SUMS --ignore-missing

A checksum file often lists every edition of a release. The --ignore-missing option skips the ones you did not download, so you only get a line for the file you have.

For a second opinion from a different program, openssl dgst -sha256 followed by the path prints the same digest.

What a match proves, and what it does not

A match proves one thing: your copy is identical to the file the published hash was calculated from. That rules out a corrupted or truncated download, and it rules out a mirror serving something different.

It does not prove the software is safe, and it does not prove who made it. It is also only as trustworthy as the place you read the hash. If someone can replace the download on a website, they can often replace the checksum printed next to it. A hash is worth more when it comes from a different place than the file: the publisher’s main site when the download comes from a mirror, for example.

Who made an app is a job for signatures, and macOS checks those itself. Gatekeeper looks for a Developer ID signature and Apple’s notarization the first time you open a downloaded app. You can run the same checks by hand:

spctl --assess --type execute --verbose /Applications/Example.app
codesign --verify --deep --strict --verbose=2 /Applications/Example.app

The first reports whether macOS accepts the app and why, for example as a notarized Developer ID app. The second confirms nothing inside the app has changed since it was signed. Gatekeeper explained covers what the warnings mean when those checks fail.

One note on the older algorithms. MD5 and SHA-1 still catch accidental corruption, but both have known weaknesses that let a determined attacker build two different files with the same hash. If a publisher offers SHA-256 alongside them, use SHA-256.

When the checksum does not match

Work through these before assuming the worst.

  1. Check you hashed the right file. The published hash is for the file as downloaded, usually a .dmg, .pkg or .zip, not for the app inside it. Safari can unpack a zip automatically, which leaves you with a folder and nothing to hash. Turn off Open “safe” files after downloading in Safari, Settings, General, and download again.
  2. Check the algorithm. A 40 character hash on the site and a 64 character hash in Terminal are two different algorithms, not a mismatch.
  3. Check the version. Each release has its own hash. A checksum for version 4.1 will never match the 4.2 download.
  4. Download it again. An interrupted download is the most common innocent cause. If the site lists a file size, compare that as well.
  5. If it still fails, delete the file. Do not open it to see what happens. Tell the publisher, since they will want to know.

Checksums for your own files

The same command is useful well beyond downloads.

Confirming a copy. After copying a large file to an external drive, hash both and compare:

shasum -a 256 ~/Movies/project.mov /Volumes/Archive/project.mov

Two identical hashes mean two identical files, whatever their names or dates say. This is also the dependable way to confirm that two files are true duplicates before deleting one; Find every copy of a file on a Mac covers locating them in the first place.

Proving what you sent. Send someone a file, then send the hash by a separate route, such as a text message. They can confirm that what arrived is exactly what left your Mac.

That second idea matters most for documents where the exact file is the point. Basalt, a Mac PDF app built around redaction, attaches a signed Ed25519 certificate to each export, as JSON plus a readable PDF. The person receiving a redacted document can check that certificate with shasum and openssl, the tools described here, without owning Basalt. If your work involves handing over redacted PDFs, How to check whether a PDF was really redacted explains the rest of that process. Basalt is free for 24 hours with every tool, then $29 for a lifetime license on up to 3 Macs.

Questions

Does a matching checksum mean the file is safe to open? No. It means the file is the one the publisher released. Whether the publisher’s software is trustworthy is a separate question, and for apps the signature and notarization checks that Gatekeeper runs are the better evidence.

Can I verify a checksum without Terminal? Not with what macOS provides in its windows. Finder’s Get Info panel does not show a hash. The Terminal method is one line, and dragging the file into the window means you never have to type a path.

The publisher only lists an MD5. Is that worth checking? Yes, for catching a broken download. It tells you the file arrived intact. It is weak evidence against deliberate tampering, so lean on the app’s signature for that.

Why does the same file give a different hash after I unzip and zip it again? Because the new archive is a different file. Compression settings, timestamps and file order all change the bytes, and the hash follows the bytes. Always hash the original download.