How to verify a Linux ISO on Mac

The ISO finished an hour ago and you are about to hand it to a virtual machine or write it to a USB stick. Back on the page you downloaded it from there was a file called SHA256SUMS, and next to that one called SHA256SUMS.gpg, and you scrolled past both.

They are worth the detour — a minute for the checksum, closer to ten the first time you do the signature — because they answer two different questions. The checksum file tells you your copy of the image arrived intact. The signature tells you the checksum file came from the distribution rather than from whoever happens to be operating the mirror you were sent to. One is about your network; the other is about trust, and no amount of re-downloading substitutes for it.

This page covers finding the real checksum file, reading the one line in it that concerns you, checking your download on a Mac, and then the signature step most people skip — including an honest account of when skipping it is defensible. The general mechanics of hashing a disk image are in hashing an ISO file on Mac; this is specifically about how Linux distributions publish their numbers and how to follow the chain back.

Where the checksums really live

Not in a blog post, not in a forum reply, not on the third-party download portal that ranked above the project. The checksum file lives in the same directory as the images, published by the distribution itself, and that adjacency is the entire point: a list sitting next to the images cannot be describing a different point release from the one you just downloaded.

Filenames differ by project, and so does the way the signature is attached.

Arch is the instructive exception. It signs the image directly, so there is no intermediate list to authenticate — which is cleaner, but only scales because there is one image. Everyone else signs a list, because one signature then covers a dozen editions and architectures at once.

Check your download against the checksum

1. Confirm which image you actually have

   Read the full filename before anything else: version including the point release, edition, and architecture. amd64 is for Intel and AMD processors; arm64 is the one an Apple Silicon Mac wants for virtualization. A checksum from the 24.04.1 directory will never match a 24.04.2 image, and because point releases roll over every few months without the headline version changing, that is the first thing to rule out.

2. Fetch the checksum file from the same directory

   Go back to the directory your ISO came from and save the checksum file, plus its signature, next to the image. If you downloaded the ISO from a mirror, take these two from the distribution’s own canonical host instead — they are a few kilobytes each, so there is no reason to economize, and it removes the mirror from one side of the comparison.

3. Find the line for your image

   The list holds one line per image in that directory: the digest, two spaces, then the filename, sometimes with an asterisk in front of the name to mark binary mode. Only the line naming your exact file matters, and the other twenty lines failing to match you is normal rather than alarming. Reading a SHA256SUMS file takes the format apart properly.

4. Hash the image and compare

   Drop the ISO into the Verify tool in Rocket Hash, paste the digest from your line, and read the verdict. The algorithm follows from the length of what you pasted, so there is nothing to configure. A 5 GB image is a few seconds of work on an internal SSD and a minute or two from a USB drive, because what you are waiting for is the disk rather than the arithmetic — SHA-256 on Apple Silicon gets through roughly 2 GB/s, more than most drives can hand over.

5. Verify the signature on the checksum file

   This is the step that turns “my download is intact” into “my download is what the distribution published”. It needs GnuPG, which macOS does not ship, and it needs the distribution’s signing key — imported by fingerprint, with the fingerprint read from the project’s own documentation rather than from whatever the download page suggests. That is the one link in the chain that happens outside the app: a signature is a claim about a key rather than arithmetic over bytes, and nothing offline can fetch a key or vouch for it on your behalf.

Reading the list, and checking more than one image

The list is plain text, one line per image, with no header and no commas — in a browser it renders as a wall of hexadecimal. This is its shape, with filler standing in for the real digests:

a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2 *ubuntu-24.04.2-live-server-amd64.iso
f6e5d4c3b2a1f6e5d4c3b2a1f6e5d4c3b2a1f6e5d4c3b2a1f6e5d4c3b2a1f6e5 *ubuntu-24.04.2-live-server-arm64.iso

Paste a whole line into Against a Checksum rather than trimming it down to the digest: the hexadecimal is the part that gets compared, and the filename riding along with it is a free confirmation that you took the line you meant to take. The asterisk before the name marks binary mode, and belongs to the format rather than to the filename.

Several images change the shape of the job, and a release directory often hands you a desktop image, a server image and two architectures at once. Put them all in the Files tool: set the Algorithm control to SHA-256, drag the folder in, and every image becomes one row — filename in bold, containing folder beneath it, size, and the digest middle-truncated with a copy button beside it. The status bar carries the summary on the left and the progress on the right.

Then use the export button. It writes a shasum-compatible manifest in the same two-column format as the block above, which you can sit beside the distribution’s own list and read down both at once — one pass over the images, one comparison of two text files, no pasting. Checking files against a manifest covers lining the two lists up.

That one run reads each image exactly once however many digests you asked for, and memory stays flat at roughly 16 MB whether the file is 700 MB or 12 GB. It pauses mid-image and resumes from the exact byte it stopped on, which matters when four images are coming off one slow external drive.

What the signature adds

The chain has four links: a key you have independently confirmed, a signature made with that key, a checksum list that signature covers, and an image the list describes. The checksum on its own gives you the last link only.

That last link is far from worthless. It catches a truncated download, a mirror holding a corrupted copy, a bad cable, and a file that quietly rotted on a drive over a year — which is most of what actually goes wrong. What it cannot catch is a mirror that replaced the image and the checksum list together, because then both sides of your comparison came from the same place. Note which of those two attacks is hard. Substituting an ISO while leaving the published SHA-256 standing means finding a second file whose digest equals one somebody else already fixed — a second preimage, which is a harder problem than a collision and is out of practical reach even against MD5. Replacing both files requires a writable mirror, which is an ordinary piece of infrastructure with ordinary failure modes.

If you do take the signature route, the first link is where it goes wrong. Importing whichever key a download page points at, then checking that page’s signature against it, proves only that the page agrees with itself. The fingerprint has to come from somewhere the project controls and an attacker does not.

So whether you need the signature depends on where your two files came from. Both of them over HTTPS from the distribution’s canonical host means a certificate has already vouched for the host, and skipping the GPG step for a desktop install is defensible on that basis. An ISO from a mirror, a torrent, a colleague, or a USB stick that has been in a drawer since last year is exactly the case the signature exists for. What a checksum proves about tampering is the general form of this argument.

The parts that are different on a Mac

• The check never leaves the machine. The window has no network access of any kind, so dragging the image in is both how you choose it and how a sandboxed app is handed permission to read it. Turn the Wi-Fi off and the verdict is identical, which is occasionally a useful thing to be able to demonstrate.
• There is no GnuPG. The checksum half is a drag and a paste; the signature half needs software you install yourself, which is the real reason most Mac users skip it.
• Browsers rename and sometimes unpack. A second download becomes … (1).iso, and Safari’s habit of opening “safe” files after downloading can expand a compressed image so that the bytes on disk are no longer the bytes the published digest describes.
• The quarantine flag is not part of the file. macOS tags downloads with an extended attribute, and extended attributes live outside the file’s data. The digest of an ISO is identical before and after Gatekeeper has had its say, so there is nothing to strip and no reason for a verification to fail on that account.

After it matches: writing it to a USB stick

Verify before you write, not after. Once the image is on a stick, hashing the device measures something else entirely: the drive is larger than the image, so reading the whole of it gives you the image plus whatever trails it, and the digest will not match. Reading back exactly as many bytes as the image holds would answer the question, but a raw device is not a file. Once the source image has verified, the write is easier to test by booting the stick.

Confirming that a copy survived a move — the ISO onto an external drive, or into a NAS share — is the ordinary two-ended check covered in verifying a file after a transfer.

Troubleshooting

My filename is not in the checksum file

You are in the wrong directory. Daily builds, nightly images and release images each have their own, and a point release rolling over replaces the contents of one. Architectures and editions are sometimes split across separate trees as well. Go back to the link you actually downloaded from rather than to the project’s front page, and take the list from there.

gpg says the key is not certified with a trusted signature

That is the normal result and not an error. GnuPG is telling you that you have not built a trust path to the key yourself, which almost nobody does outside a web of trust. What matters is the line above it — a good signature — and that the fingerprint matches what the distribution documents. If you want the warning to go away you can sign the key locally, but it changes nothing about the verification.

The checksum does not match after two downloads

If both copies have the same digest and neither matches the list, your network is not the problem and re-downloading again will not help. Either you have the wrong list for the image, or the mirror is serving something other than what the distribution published. Switch to the canonical host for both files and try once more, then work through what to do when a checksum does not match, which ranks the nine causes by likelihood.

I downloaded the ISO by torrent

BitTorrent verifies every piece against hashes held in the torrent file as it arrives, so a completed torrent is internally consistent and almost certainly not corrupted. What that does not establish is that the torrent file itself was the right one — the piece hashes are only as trustworthy as wherever you got the .torrent or the magnet link. Check the finished ISO against the signed list anyway; it takes seconds and it is the only part of the chain a torrent cannot supply.