Create and Verify SHA Checksums with shasum

shasum is the Perl-based checksum tool you reach for on a box that lacks sha256sum, and its default algorithm quietly trips people up. It defaults to the weaker SHA-1, so this guide gets you calculating an explicit SHA-256 checksum, verifying a later copy against it, reading a failed check correctly, and knowing which options change how the input is read.

Allow about ten minutes. You need a shell and the shasum command from Perl. The examples below use shasum 6.04 from Perl package 5.38.2-3.2ubuntu0.6 on the reference system. No elevated privileges are normally needed. You only need sudo if the file you are checking is not readable by your account.

Checkpoint: this guide creates a checksum file only. It does not alter the downloaded file. Treat a checksum as useful evidence about integrity, not proof that the file came from a trustworthy publisher.

1. Confirm the installed command

Check the executable and its version before putting it into a script:

$ command -v shasum
/usr/bin/shasum
$ shasum --version
6.04
$ dpkg-query -W -f='${Package} ${Version}\n' perl
perl 5.38.2-3.2ubuntu0.6

The command is a Perl utility implemented with the Digest::SHA module. Its default algorithm is SHA-1, so choose an algorithm explicitly for new checksum files. SHA-256 is the practical default for most download and archive checks.

2. Calculate a SHA-256 checksum

Replace /path/to/download.iso with the file you actually downloaded:

$ shasum --algorithm 256 /path/to/download.iso
ba7816bf8f01cfea414140de5dae2223b00361a396177a9cb410ff61f20015ad  /path/to/download.iso

The output has three useful parts: the hexadecimal digest, a marker describing how the input was read, and the file name. The blank marker shown here is text mode. On Linux, the important comparison is the complete digest, not the spacing around it.

Short option -a 256 is equivalent to --algorithm 256:

$ shasum -a 256 /path/to/download.iso

Checkpoint: run the command twice. The digest should be identical both times. If the file is being written by another process, wait for that process to finish before calculating or verifying it.

3. Save a checksum file without losing an existing one

For a file you plan to distribute or verify later, save the command's complete output:

$ shasum -a 256 /path/to/download.iso > /path/to/download.iso.sha256
$ sed -n '1p' /path/to/download.iso.sha256
ba7816bf8f01cfea414140de5dae2223b00361a396177a9cb410ff61f20015ad  /path/to/download.iso

The redirection operator > truncates an existing destination before shasum runs. That is a destructive overwrite of the checksum file, even though the input stays untouched. If the checksum file matters, choose a new name, copy the old file first, or use a shell and workflow that refuses clobbering. Do not replace a checksum supplied by a publisher with one calculated from an untrusted or incomplete download.

4. Verify the file later

Use --check with the saved checksum file. The algorithm is encoded by the digest length for common SHA variants, so this ordinary verification command is enough for the SHA-256 file above:

$ shasum --check /path/to/download.iso.sha256
/path/to/download.iso: OK

The check reads the file name from the checksum line and recalculates the digest. A changed file produces a failure such as FAILED; a missing file produces an error. A non-zero exit status is the result that scripts should act on:

$ shasum --check --status /path/to/download.iso.sha256
$ printf 'verification status: %s\n' "$?"
verification status: 0

--status prints nothing, including no successful OK lines. Use --quiet instead when you want failures reported but do not want an OK line for every successful file. Capture $? immediately; running another command first replaces the status you meant to inspect.

5. Check more than one file

A checksum file can contain one line per input. Generate one for each selected file, then check the collection:

$ shasum -a 256 /path/to/kernel.img /path/to/rootfs.img > /path/to/images.sha256
$ shasum -c /path/to/images.sha256
/path/to/kernel.img: OK
/path/to/rootfs.img: OK

For automation, add --status and fail the job when the command returns non-zero. If an expected file may be absent and that should not fail the whole check, --ignore-missing suppresses failure and status output for missing files. Use it carefully: ignoring a missing release artefact can turn an incomplete deployment into a false success.

6. Understand text, binary and special input modes

The default is text mode, selected explicitly with -t or --text. -b or --binary selects binary mode. The checksum line records the choice with a space for text and * for binary. Use the mode specified by the publisher when the checksum file came from elsewhere; do not change it just to make a failed check pass.

shasum reads standard input when no file is supplied or when the file name is -:

$ printf 'abc' | shasum -a 256
ba7816bf8f01cfea414140de5dae2223b00361a396177a9cb410ff61f20015ad  -

The newline matters. printf 'abc' and printf 'abc\n' are different byte sequences and therefore have different digests. When a pipeline is involved, inspect the producer as well as shasum if the result does not match published data.

The less common -U universal-newlines mode and -0 bits mode are specialised compatibility features. Bits mode treats ASCII 0 and 1 as bits and ignores other characters. Use them only when the input specification explicitly requires those interpretations. For SHA-512/224 and SHA-512/256, pass the algorithm explicitly, for example shasum -a 512224 -c checksumfile.

7. Diagnose a failed verification

First check that you are verifying the intended checksum file and that its recorded path points to the intended file. Then inspect the file size and permissions without changing either:

$ ls -l /path/to/download.iso /path/to/download.iso.sha256
$ test -r /path/to/download.iso && echo 'input is readable'
$ shasum -c /path/to/download.iso.sha256
/path/to/download.iso: FAILED
shasum: WARNING: 1 computed checksum did NOT match

A failed digest means the bytes differ, not that shasum repaired anything. Re-download the file or locate the correct published checksum. Do not edit the checksum line to match your local file. If the checksum file itself has malformed lines, --warn reports them; --strict makes improperly formatted lines cause a non-zero result.

Do not assume that a successful digest establishes authenticity. Obtain the checksum through the publisher's trusted channel, and use a signed release file or signature verification when the project provides one. A checksum copied from the same compromised download location can faithfully describe an attacker's replacement.

Done means