Verify Downloads and Files with sha256sum

You will finish with a repeatable way to calculate a SHA-256 digest, save it as a manifest, and check that a file still matches. The examples use GNU coreutils 9.4, installed here as Ubuntu package version 9.4-3ubuntu6.3.

Allow about ten minutes. You need a shell, a file to hash, and its expected SHA-256 value or a checksum manifest from a trusted source. All commands in this guide are ordinary user commands. You do not need sudo, and you should not use it to compensate for a wrong path or an untrusted checksum.

1. Confirm the installed command

Check which executable your shell will run and record the package version:

$ command -v sha256sum
/usr/bin/sha256sum
$ sha256sum --version | head -n 1
sha256sum (GNU coreutils) 9.4
$ dpkg-query -W -f='${Package} ${Version}\n' coreutils
coreutils 9.4-3ubuntu6.3

The exact package revision can differ on another machine. The local manual describes sha256sum as a tool that prints or checks 256-bit checksums. It reads standard input when no file is supplied, or when the file name is -.

2. Calculate a digest for one file

Set a file path you have checked, then pass it as one quoted argument:

$ FILE='/path/to/download.iso'
$ sha256sum "$FILE"
0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef  /path/to/download.iso

The 64 hexadecimal characters are the SHA-256 digest. The file name is printed after two spaces in the usual text-mode output. The value above is only a shape example, not a digest to copy into a real verification.

To hash data from a pipeline, use standard input explicitly:

$ printf '%s\n' 'text to hash' | sha256sum
e1f...  -

The digest in this second example depends on the exact bytes, including the newline added by printf. A shell variable or text editor can add or remove bytes, so hash the file you actually intend to distribute.

3. Compare with a trusted published value

A checksum only detects a difference from the value you compare it with. Obtain the expected value through a trusted channel, preferably the software project's HTTPS download page or a separately authenticated release signature. A checksum copied from the same untrusted download location does not establish authenticity.

Compare the value without changing the file:

$ EXPECTED='0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef'
$ ACTUAL=$(sha256sum "$FILE" | awk '{print $1}')
$ test "$ACTUAL" = "$EXPECTED" && echo 'SHA-256 matches' || echo 'SHA-256 does not match'
SHA-256 matches

Keep the expected value in lower case when you paste it. Hexadecimal case does not change the mathematical value, but an exact comparison treats upper and lower case as different text.

4. Create a checksum manifest

When you control the file and need to verify it later, save the complete output as a manifest. Choose a new destination or inspect an existing one first, because shell redirection with > truncates an existing file before sha256sum starts:

$ MANIFEST='/path/to/download.iso.sha256'
$ test ! -e "$MANIFEST" || { echo "refusing to overwrite $MANIFEST"; exit 1; }
$ sha256sum "$FILE" > "$MANIFEST"
$ cat "$MANIFEST"
0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef  /path/to/download.iso

The manifest contains both the digest and the path, so it can be checked by the same program. If you created the manifest only as a temporary record, retain it until the file has been checked, then remove that generated record using your normal file-management process. The original input file is not changed by sha256sum.

5. Verify the manifest and read the result

Use --check to read the manifest and hash the named file again:

$ sha256sum --check "$MANIFEST"
/path/to/download.iso: OK
$ printf 'exit status: %s\n' "$?"
exit status: 0

Exit status 0 means every properly formatted entry checked successfully. A changed file produces FAILED and a non-zero status. A missing file is also a failure by default:

$ sha256sum --check "$MANIFEST"
sha256sum: /path/to/download.iso: No such file or directory
/path/to/download.iso: FAILED open or read
sha256sum: WARNING: 1 listed file could not be read
$ printf 'exit status: %s\n' "$?"
exit status: 1

For scripts, --status suppresses output and leaves the exit status as the signal. For a human-readable check, omit it. --quiet hides successful OK lines but still reports failures.

$ if sha256sum --status --check "$MANIFEST"; then
>     echo 'verified'
> else
>     echo 'verification failed' >&2
>     exit 1
> fi
verified

Do not use --ignore-missing for a complete release check unless missing files are deliberately optional. It suppresses failure and status for missing entries, which can turn an incomplete directory into a misleading pass.

6. Handle text, binary and unusual names

The manual exposes --binary and --text, with text mode as the default. On GNU systems there is no difference between the two modes, but --binary is useful when a manifest must state its intended convention clearly:

$ sha256sum --binary "$FILE"
0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef */path/to/download.iso
$ sha256sum --text "$FILE"
0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef  /path/to/download.iso

The asterisk marks binary mode. Use the mode expected by the publisher when exchanging manifests across operating systems.

For machine-readable output, --zero ends each record with a NUL byte and disables file-name escaping. That is safer than newline-delimited parsing when names can contain newlines, but the consumer must understand NUL-delimited records. Do not use it for a manifest format that expects ordinary lines.

7. Diagnose malformed manifests

A checksum line must come from a former sha256sum output or match its format. Use --warn to report improperly formatted lines, and --strict to make such lines a non-zero-status error. These options matter only with --check:

$ sha256sum --check --warn "$MANIFEST"
/path/to/download.iso: OK
$ printf 'exit status: %s\n' "$?"
exit status: 0

If a check fails, first inspect the manifest and the exact path it names. Confirm that the file was not partially downloaded, transformed by an archive tool, or replaced after the manifest was made. Restore the original file or obtain a fresh copy; there is no repair operation that can turn a changed file back into the expected bytes.