Verify File Integrity with md5sum

md5sum builds a checksum file that catches an accidental or damaged change to a file. This guide gets you to a repeatable check that returns a useful shell status, using GNU coreutils 9.4, installed here as package version 9.4-3ubuntu6.3. Allow about ten minutes; you need a shell and a file you can read, and none of the normal commands require elevated privileges.

Warning: MD5 is not suitable for security-related decisions. It is useful for catching accidental changes and for matching a legacy checksum from a trusted source. If an attacker might choose or replace both the file and its checksum, use a stronger mechanism, such as a signed release or a checksum made with sha256sum.

1. Check the installed command

Start by confirming the binary and its version. This is a read-only checkpoint and needs no sudo:

$ command -v md5sum
/usr/bin/md5sum
$ md5sum --version | head -2
md5sum (GNU coreutils) 9.4
Copyright (C) 2023 Free Software Foundation, Inc.

The command accepts file names as arguments; with no file, or with -, it reads standard input. The installed manual calls its normal output a checksum, a mode marker and the file name. GNU systems do not distinguish text mode output from binary mode, though the options stay available for scripts that need to state their intent.

2. Create a checksum record

Choose the file you want to record. The example creates a disposable file under /tmp, so it cannot touch a project file:

$ work_dir=$(mktemp -d)
$ printf '%s\n' 'release candidate 1' > "$work_dir/release.txt"
$ md5sum "$work_dir/release.txt" > "$work_dir/release.md5"
$ cat "$work_dir/release.md5"
570a08577d8698d3a1d725c43cbbabe7  /tmp/tmp.XXXXXX/release.txt

Your hexadecimal digest will differ if the temporary directory name or file content differs. The two spaces before the path are part of the usual text-mode output. Keep the checksum file alongside the download or artefact it describes, and move it over a channel you trust.

For a file that may move later, the checksum record still holds the original path. Verification uses that path to find the file, so if you move the file, update the record deliberately rather than assuming the old record will follow it.

3. Verify the record with readable output

Use --check to read a checksum file and test the referenced file:

$ md5sum --check "$work_dir/release.md5"
/tmp/tmp.XXXXXX/release.txt: OK
$ printf 'check status: %s\n' "$?"
check status: 0

The temporary directory component is abbreviated in this guide; your shell prints its real name. The result that matters is OK and a zero status. A mismatch shows as FAILED and returns non-zero, and that status is what a script should act on rather than scraping the displayed text.

Checkpoint: change the test file, then verify that a mismatch is detected:

$ printf '%s\n' 'release candidate 2' > "$work_dir/release.txt"
$ md5sum --check "$work_dir/release.md5"
/tmp/tmp.XXXXXX/release.txt: FAILED
md5sum: WARNING: 1 computed checksum did NOT match
$ printf 'check status: %s\n' "$?"
check status: 1

Do not replace a known-good file just because a check failed. Decide first whether the change was expected, whether the wrong file got selected, or whether the checksum record came from an untrusted source.

4. Use status-only checks in scripts

--status suppresses normal output and leaves the result in the exit status, which is handy in a conditional:

$ if md5sum --status --check "$work_dir/release.md5"; then
>     echo 'checksum matches'
> else
>     echo 'checksum failed'
> fi
checksum failed

Because the file was deliberately changed in the previous step, the failure is expected here. Restore the original content and repeat the check:

$ printf '%s\n' 'release candidate 1' > "$work_dir/release.txt"
$ md5sum --status --check "$work_dir/release.md5"
$ printf 'check status: %s\n' "$?"
check status: 0

A command with no output is easy to mistake for one that did not run. Print the status when testing by hand; in a script, branch on it immediately and stop or report the failure according to the surrounding workflow.

5. Handle missing files and malformed records

A checksum file names the files it checks, so removing the target or using the wrong working directory can produce a missing-file error. Inspect the record and the target before changing anything:

$ sed -n '1p' "$work_dir/release.md5"
$ test -r "$work_dir/release.txt" && echo 'target is readable'
target is readable

When a set of records contains optional files, --ignore-missing tells the checker not to fail or report status for missing files. Use it only when omission is genuinely allowed: for a release manifest, silently ignoring a missing artefact can hide an incomplete download, so the default behaviour is usually safer.

For strict automation, --strict makes improperly formatted checksum lines cause a non-zero result, and --warn reports malformed lines while checking. Both are verification-only options, alongside --quiet, which hides successful OK lines without hiding failures.

6. Choose the right algorithm

Do not use md5sum to authenticate software, prove who created a file, protect passwords, or make a security decision. MD5 collisions are a known security problem. Prefer sha256sum, sha512sum or b2sum when the checksum is part of a security boundary, and prefer a signed package or release when authenticity matters.

Changing the algorithm also changes the record and the checker. A SHA-256 manifest must be created and checked with sha256sum; do not feed it to md5sum --check and expect a meaningful result.

7. Clean up the test safely

The example changed only files under the temporary directory. Once you have finished inspecting the results, remove that exact directory:

$ rm -rf -- "$work_dir"
$ test ! -e "$work_dir" && echo 'temporary test directory removed'
temporary test directory removed

Warning: this deletion is irreversible. Do not adapt the command by swapping in a broader path, and do not run it against a directory that holds real work. If you used your own files instead, keep the checksum record and remove nothing until the verification result is recorded.

Done means