Python hashlib — Hash Text, Bytes, and Files
A hash turns a block of bytes into a short fixed-size fingerprint. The same bytes always give the same fingerprint, and a change to even one byte gives a different one. Programs use that fingerprint to spot a changed file, to check a download, and to name stored data by its content. This guide hashes bytes and text with the hashlib module, feeds data in chunks, hashes a file in blocks, signs a short message with a key, and ends with the traps that come from hashing text without encoding it and from mixing the two digest forms.
Written November 13, 2026 · Tested with Python 3.12.3 · 9 min read
- The main program: hash bytes and read the hexdigest
- Text: encode before hashing
- Update: feed data in chunks
- Files: hash in blocks
Written November 13, 2026
Tested with Python 3.12.3
What this guide is
The hashlib module builds hash objects. A hash object takes bytes through its update method, or in the constructor call itself, and then reports the fingerprint in two forms: digest, the raw bytes, and hexdigest, the same bytes written as a hexadecimal string. The sha256 algorithm always reports 32 bytes, which is 64 hexadecimal characters, no matter how long the input was. A hash is not encryption: there is no key and no way back from the fingerprint to the data. Its use is comparison. Two blocks with the same fingerprint are, for practical work, the same block, and two blocks with different fingerprints are certainly different.
The main program: hash bytes and read the hexdigest
Pass bytes to the sha256 constructor and read the hexdigest. The result for a given input never changes, on any machine, in any run:
import hashlib
digest = hashlib.sha256(b"hello")
print(digest.hexdigest())
print(len(digest.hexdigest()))
print(digest.digest_size)
print(type(digest.hexdigest()).__name__)
The exact output:
2cf24dba5fb0a30e26e83b2ac5b9e29e1b161e5c1fa7425e73043362938b9824
64
32
str
The fingerprint is 64 characters long and the digest size is 32 bytes, because each byte takes two hexadecimal characters. The hexdigest is a string, so it can be printed, stored in a text file, placed in a filename, or sent in a message without any extra encoding step. Nothing here hides the input: anyone with the same bytes gets the same fingerprint, which is the point when the goal is to check that two copies match.
Text: encode before hashing
Hash objects take bytes, not strings. Text goes in after an encode call, and the encoding is part of the result: the same characters encoded in a different way are different bytes and can hash differently. With the usual UTF-8 encoding, text and the matching byte literal agree:
import hashlib
from_text = hashlib.sha256("hello".encode("utf-8")).hexdigest()
from_bytes = hashlib.sha256(b"hello").hexdigest()
print(from_text == from_bytes)
print(hashlib.sha256("Hello".encode("utf-8")).hexdigest() == from_bytes)
print(hashlib.new("sha256", b"hello").hexdigest() == from_bytes)
The exact output:
True
False
True
The encoded text matches the byte literal. The capital H version does not match, because one different byte is enough. The last line shows the new function, which takes the algorithm name as a string; the named constructors such as sha256 read better when the algorithm is fixed in the code, and new is the form to use when the name comes from data, such as a settings value. A program that hashes text in one place and bytes in another must fix one encoding and use it in both places, or the comparison fails on data that looks the same.
Update: feed data in chunks
The constructor call is a shortcut for creating an empty object and calling update once. Calling update several times hashes the joined bytes, in order. The split form gives the same fingerprint as the one-shot form:
import hashlib
whole = hashlib.sha256(b"hello world").hexdigest()
split = hashlib.sha256()
split.update(b"hello ")
split.update(b"world")
print(split.hexdigest() == whole)
print(split.hexdigest())
split.update(b"!")
print(split.hexdigest() == whole)
The exact output:
True
b94d27b9934d3e08a52e52d7da7dabfac484efe37a5380ee9088f7ace2efcde9
False
Two update calls matched the single call. A third update after the comparison changed the fingerprint, because the object keeps every byte it was fed; hexdigest reports the state so far and does not reset it. Chunk size does not matter to the result, only the byte sequence does, which is what makes the next section work: a file can be fed in small blocks and still match a hash of the whole content at once.
Files: hash in blocks
A file is hashed by opening it in binary mode and feeding blocks to update until a read returns empty bytes. The file itself is never loaded whole, so a file of any size hashes in the same small amount of memory:
import hashlib, pathlib, tempfile
data = b"first line\nsecond line\n"
with tempfile.TemporaryDirectory() as td:
path = pathlib.Path(td) / "notes.txt"
path.write_bytes(data)
hasher = hashlib.sha256()
with path.open("rb") as handle:
for block in iter(lambda: handle.read(4), b""):
hasher.update(block)
print(hasher.hexdigest())
print(hasher.hexdigest() == hashlib.sha256(data).hexdigest())
print(path.stat().st_size)
The exact output:
c2097f55f01fc297fc7f4acf21438123e06e4d409a818524428534e850642f4f
True
23
The block size here is 4 bytes only so the loop visibly runs several times; real code uses a larger block, such as 65536 bytes, and gets the same fingerprint. The iter call with a sentinel is the standard way to turn a read method into a loop: it calls the read again and again and stops when the returned value equals the empty bytes given as the sentinel. Open the file in binary mode for this work. Text mode can change line endings or decode the bytes, and either change would make the fingerprint describe something other than the file on disk.
Algorithms: names and output sizes
The module offers several algorithms. They differ in output size and in how much trust they still carry. The guaranteed set is the group the module promises on every platform:
import hashlib
for name in ["md5", "sha1", "sha256", "sha512"]:
h = hashlib.new(name, b"hello")
print(name, len(h.hexdigest()), h.digest_size)
print("sha256" in hashlib.algorithms_guaranteed)
print(sorted(hashlib.algorithms_guaranteed) == sorted(hashlib.algorithms_guaranteed))
The exact output:
md5 32 16
sha1 40 20
sha256 64 32
sha512 128 64
True
True
The hex lengths are twice the digest sizes, as before. Size is not the only difference. The md5 and sha1 algorithms have known collision attacks, where two different inputs with the same fingerprint can be built on purpose, so they no longer suit a check that an opponent might try to fool. They still appear in old records and in checksums published by other tools, and hashlib can still read those values for comparison. For a new fingerprint that must stand up to tampering, sha256 is the common default, and sha512 is the larger form from the same family.
A key: hmac and compare_digest
A plain hash can be rebuilt by anyone who has the data, so it cannot prove who made a fingerprint. The hmac module mixes a secret key into the hash. Only a holder of the key can produce the right tag for a message, and compare_digest checks two tags without the timing leak of a plain equality test on secret values:
import hashlib, hmac
key = b"secret-key"
message = b"transfer 9"
tag = hmac.new(key, message, hashlib.sha256).hexdigest()
print(tag)
print(hmac.compare_digest(tag, hmac.new(key, message, hashlib.sha256).hexdigest()))
print(hmac.compare_digest(tag, hmac.new(b"wrong-key", message, hashlib.sha256).hexdigest()))
print(hmac.compare_digest(tag, tag.upper()))
The exact output:
afcc5ff6345de409d76e5104c3f11100ed61bc2747c762c156559abfb2f107b1
True
False
False
The same key and message rebuilt the same tag, so the check passed. A wrong key failed, and so did an uppercased copy of the right tag, because the comparison is exact, character for character. Use compare_digest for tags and other secret-derived values instead of the equality operator; for plain file fingerprints, where nothing is secret, equality is fine. A key belongs in a program the way other secrets do: read it from outside the code, never write a real one into a guide, a repository, or a log. The key in this example is a stand-in that signs one short message so the outputs can be shown exactly.
Three traps: text without encoding, the two forms, and one changed byte
import hashlib
try:
hashlib.sha256("hello")
except TypeError as error:
print(type(error).__name__)
h = hashlib.sha256(b"hello")
print(type(h.digest()).__name__, len(h.digest()))
print(type(h.hexdigest()).__name__)
print(hashlib.sha256(b"hello").hexdigest() == hashlib.sha256(b"hellp").hexdigest())
print(hashlib.sha256(b"hello").hexdigest()[:8])
The exact output:
TypeError
bytes 32
str
False
2cf24dba
The string call failed before any hashing happened. The digest is 32 bytes, the hexdigest is a string, and the changed input failed the comparison. The last line shows a common storage shortcut, keeping the first characters of a hexdigest as a short label. A short label is fine for display and for naming, but a check that matters should compare the full fingerprint: a short prefix is far easier for two different inputs to share by chance. Pick one form, hexdigest in most code, and use it at every point where fingerprints are made, stored, and compared.
Which choice for which job
| Job | Choice | Why |
|---|---|---|
| Check a file | sha256 in blocks | Same fingerprint, small memory |
| Hash short bytes | Constructor call | One line, whole input at once |
| Data arrives in parts | update calls | Joined bytes hash the same |
| Text input | encode first | Hash objects take bytes only |
| Name from settings | new with a string | Algorithm chosen at run time |
| Prove a key holder | hmac tag | Only the key holder can sign |
| Compare a secret tag | compare_digest | No timing leak on secrets |
| Match an old record | md5 or sha1 | Reads values other tools made |
Checklist
- Before hashing text, encode it, and fix the one encoding the whole program uses for hashes.
- Before hashing a file, open it in binary mode and feed blocks to update; never load a large file whole for a fingerprint.
- Before comparing fingerprints, confirm both sides use the same algorithm and the same form, digest or hexdigest.
- Before trusting a fingerprint against tampering, use sha256 or stronger; treat md5 and sha1 values as read-only legacy data.
- Before comparing a tag or other secret-derived value, use compare_digest, not the equality operator.
- Before storing a shortened fingerprint as an identifier, check how many items it must tell apart; a check that matters compares the full value.
Related guides on this site
- Python Files — open, read, write, and with — the binary and text modes the file section opens with.
- Python csv — Reading Rows, DictReader, Writing, and Quoting — another byte-to-rows path where encoding and line endings matter.
- Python JSON — dumps, loads, and Files — turning data into text that can then be hashed or stored.
- Python subprocess — run, Capture, check, and Timeout — running the checksum tools of the operating system as a child instead, when that is the job.
Sources
- Python Standard Library, hashlib — the hash objects, update, digest and hexdigest, the named constructors and new, algorithms_guaranteed, and file hashing in blocks.
- Python Standard Library, hmac — keyed hashing with new, and compare_digest for checking digests and tags.
Keep Exploring
The full Python hub \u2014 language basics, the standard library, and data tools.
Every guide on the site in one list, grouped by topic.
Every browser-only checker and verifier on the site.
The C++, Python, Sysadmin, Rust, Go, and TypeScript hubs.