Python

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

By the end of this guide
  • 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:

Python
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:

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:

Python
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:

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:

Python
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:

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:

Python
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:

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:

Python
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:

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:

Python
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:

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

Trap
Passing a string straight to a hash raises TypeError at once, which is the module refusing to guess an encoding. The digest and hexdigest forms hold the same bytes in two types, and code that compares one form against the other never matches. And a one-letter change gives a wholly different fingerprint, with no closeness signal in it:
Python
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:

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.

Sources

Keep Exploring