What is a SHA256SUMS file, and how do you read one?

A checksum file is a plain text list. Each line describes one file and has exactly two fields: the digest, then the name of the file it belongs to, separated by two spaces. That is the entire format. No header, no version number, no metadata, no closing line — which is why a list written in the 1990s still checks out today, and why a tool that has never heard of your publisher can read theirs.

The name on disk varies and means nothing in particular. SHA256SUMS, sha256sum.txt, CHECKSUMS, MD5SUMS, ubuntu-24.04.iso.sha256 and SHASUMS256.txt are all the same two-column format; the filename is the publisher telling you which algorithm they used, and sometimes they are wrong about it. The digests themselves are the authority, because the number of characters gives the algorithm away.

This page takes one line apart field by field, explains the asterisk that sometimes appears before a filename, and finishes with the shortest route from “here is a list of fourteen files” to “my one download is fine”. If your question is the broader one of what a digest proves, what a checksum actually is answers that first.

One line, field by field

Here is a two-line manifest whose digests you can confirm for yourself in about ten seconds, which makes it a better teaching example than any real download — every claim on this page can be checked against it.

e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855  empty.txt
ba7816bf8f01cfea414140de5dae2223b00361a396177a9cb410ff61f20015ad  abc.txt

Both of those are NIST's own published test values: the first is the SHA-256 of nothing at all, the second of the three letters abc. You can confirm the second one without leaving your desk — type abc into the Text tool and the SHA-256 row resolves, as you type, to exactly those 64 characters. That tool is free, so hashing a string as you type it is the quickest way to sanity-check any digest on this page, including the ones in your own checksum file.

One warning if you try it: type the three letters and nothing else. A trailing newline is one more byte of input and an entirely different digest, and it accounts for most of the cases where a value you worked out yourself refuses to match the one a list claims. Why two tools give different hashes starts with exactly that.

Read one line of the list left to right:

• The digest. 64 hexadecimal characters for SHA-256. Lowercase by convention, though uppercase means exactly the same number — hexadecimal has no case, and anything comparing two digests properly accepts either.
• The separator. Two spaces, or one space and one asterisk. Nothing else. This is the field people break.
• The filename. Written exactly as it was when the list was made, including any folder path in front of it. iso/ubuntu-24.04.iso, ./ubuntu-24.04.iso and ubuntu-24.04.iso are three different lines describing the same file from three different starting points — the path is a note about where it was standing, not an address anything has to honor.

There is no field for the file's size, its date, or the algorithm's name. The order of the lines carries no meaning either — it is whatever order the tool walked the files in.

What the asterisk before a filename means

Some lines have two spaces; some have a space and then an asterisk glued to the filename:

ba7816bf8f01cfea414140de5dae2223b00361a396177a9cb410ff61f20015ad *abc.txt

The asterisk is not a warning, a flag on the file, or part of its name. It records which mode the file was read in: two spaces means text mode, * means binary mode. The distinction is a fossil from systems that translated line endings on the way in and out, where reading a file as text genuinely changed the bytes the hash saw. On macOS and Linux there is no translation, so the two modes are identical and the digest is the same either way.

Practical consequence: ignore it. Publishers use both forms, neither changes a single character of the digest, and the digest is the only field you are ever comparing against your own. The only time the choice is yours is if you are writing a list by hand and wondering which to type — use two spaces, because that is what the rest of the world's lists look like.

The other format you will meet

A minority of tools write a tagged line instead, with the algorithm spelled out and the filename in parentheses:

SHA256 (abc.txt) = ba7816bf8f01cfea414140de5dae2223b00361a396177a9cb410ff61f20015ad

This is the shape macOS's own md5 utility produces, so a digest somebody on a Mac pastes into a ticket often arrives looking like this. It is more informative than the two-column form, since it names the function instead of leaving you to count characters. It is also much rarer, which is why a publisher who uses it gets asked by users why their checksum file “looks wrong”.

A third shape turns up in tickets and mailing lists and is not the tagged format at all — SHA2-256(abc.txt)= ba7816bf…, which is OpenSSL's output, with no space before the parenthesis, none before the =, and a hyphenated algorithm name in version 3. Anything expecting a list refuses it, with the same complaint it makes about a single-space separator. Treat it as one digest somebody sent you, not as a manifest: the hexadecimal after the = is the part you paste into Against a Checksum.

One trap specific to Macs: that same md5 utility has a reversed output mode which looks like the two-column format but puts a single space between the fields. A list built that way is rejected by anything expecting the standard separator, which is a thoroughly annoying twenty minutes if you do not know to look for it. If you are the one producing a list other people have to check, exporting one from the Files tool writes the two-space form without giving you the chance to get it wrong.

Which algorithm is in the file

Count the characters in the first column. That is usually the whole investigation.

The two ambiguous rows are worth knowing about. Length cannot distinguish SHA-256 from SHA3-256, or SHA-512 from SHA3-512, because those pairs output the same number of bits from completely different internal designs — so only the publisher's own words settle it, and in practice a file called SHA256SUMS is SHA-2 unless it says otherwise. Identifying a hash from the value alone works through the rest of the clues.

Checking your one download against it

The usual situation is lopsided: the list covers fourteen files and you downloaded one. The other thirteen are not your problem — find the line whose filename matches the file you have, and check that line.

1. Select the whole line in the list and copy it, digest and filename together. There is no need to trim it back to the hexadecimal.
2. Open Verify in the sidebar and leave the segmented control on Against a Checksum.
3. Drag your download into the drop well, or pick it with the Replace… link. The well shows the name and the size, which is the moment to notice you have grabbed a half-finished .part file.
4. Paste the line. The algorithm is read off the length of the digest, so a 64-character value is treated as SHA-256 without you declaring anything — the same counting you did against the table above.
5. Read the sentence underneath. A green seal means your copy holds the same bytes the line describes; the other answer says so plainly, with no amber in between.

The filename at the end of the line is the publisher's, not yours, and the difference is harmless: a browser that saved the image as ubuntu-24.04.iso(1) changed the name and not one byte of the contents, so the line still verifies. Picking the right line is what actually matters. A release directory routinely holds a desktop image, a server image and one build per architecture, each with its own digest, so comparing your download against the line above the one you wanted produces a confident failure that says nothing whatever about your download. Verifying a SHA-256 checksum walks the same route with a single pasted value rather than a whole line, and what to do when a checksum does not match takes the failure apart.

When you have all fourteen files rather than one of them — a mirror you are auditing, a folder you mean to re-check next year — stop pasting lines one at a time. Hash the folder in Files, use the export button to write the results out in this same two-column format, and compare the two lists: checking files against a manifest is that job end to end. None of that happens in a web browser, incidentally. A page can hash text you paste into it, but reading a 5 GB image off your disk and comparing it with a line of a list is what Verify and Files are for, which is why the one-file route above goes through the app.

What the file cannot tell you

A checksum file is a statement about bytes made by whoever wrote it. It is not a statement about who that was. If someone can replace the download on a server, they can replace the SHA256SUMS next to it in the same breath, and the two will agree perfectly.

That is why careful publishers ship a third file: SHA256SUMS.gpg or SHA256SUMS.asc, a detached signature over the list. You verify the signature against a key you obtained some other way, and only then does the list become evidence of origin rather than evidence of arrival. Verifying a Linux ISO shows both halves in sequence, and what a digest proves about tampering explains why the distinction is not pedantry.

Troubleshooting

Nothing will read the list

Then it is not in the format, whatever it looks like at a glance. In order of likelihood: one space instead of two in the separator; you have the GPG signature rather than the list; the download handed you an HTML page where you wanted a text file; or the first column is not hexadecimal at all because something helpfully wrapped the long lines. Open it in a plain text editor and look at a single line — that settles it in about five seconds.

The list names a file that is plainly there

The line is carrying a character you cannot see. Everything after the separator counts as the filename, so a list written on Windows asks for ubuntu-24.04.iso followed by a carriage return, and a name that looks perfectly normal refuses to match anything — including when you copy that line out and paste it somewhere. Open the list in a plain text editor that can show invisible characters, or re-save it with Unix line endings, and the names resolve. A third space in the separator does the same damage more quietly, leaving a filename that begins with a space.

The digest is uppercase and mine is lowercase

Not a problem. Hexadecimal has no case — FF and ff are the same byte — so the two values are the same number written two ways, and Windows tooling printing uppercase is a house style rather than a difference. If you are reading across two values by eye, ignore the case and compare the characters.

My file is not in the list at all

Check the version, the architecture and the mirror. Publishers commonly keep a separate list per release directory, and an Apple Silicon build, an Intel build and a universal build are three different files with three different digests. A list from yesterday's release will not mention today's filename.

The names in the list have folders in front of them

Then the list was written from one level up, and the paths describe that author's folder rather than yours. For a single line it makes no difference: you hand the file over yourself by dropping it into Against a Checksum, so nothing ever resolves the path and a list whose second column stopped being true years ago still checks out. It only matters when you are lining a whole list up against a whole folder, which checking files against a manifest covers properly.