hashlib — hash algorithms

hashlib SHA-256 and MD5 for byte data, including the TypeError for str, hash.copy, and why a single digest is not a password store.

模块页正文目前为英文。

The hashlib module provides a common interface to hash algorithms such as SHA-256, SHA-3, and BLAKE2. MD5 and SHA-1 are available but have known collision weaknesses; official documentation says to choose a hash function wisely. Constructors take bytes, not str: passing a string raises TypeError: Strings must be encoded before hashing.

A single sha256(password) or md5(password) call is not a password-storage scheme. Official documentation provides hashlib.pbkdf2_hmac and hashlib.scrypt as key-derivation functions, which still require a unique salt and a work factor chosen for the situation. This page does not present a complete password-storage recipe and does not treat hashlib as a substitute for that design. The secrets module is the standard-library place to generate tokens and compare secret values carefully.

Examples were checked against Python 3.13. See the official documentation for the complete API.

Python reference overview →

sha256, update, and copy

hashlib.sha256(data) returns a hash object seeded with data. Repeated update() calls are equivalent to hashing the concatenation. hexdigest() returns a hexadecimal string; digest() returns raw bytes. copy() clones the current state so you can continue one object without changing the other. The SHA-256 hex digest of b"abc" is the well-known test vector shown below.

hashlib.sha256, hash.update, hash.hexdigest, hash.copy

hashlib.sha256(data=b'', *, usedforsecurity=True)
hash.update(data)
hash.hexdigest()
hash.digest()
hash.copy()

Hash bytes with SHA-256, including chunked update and a cloned state. Strings must be encoded first.

ParameterDescription
dataBytes to hash. A str is not accepted; encode it explicitly, for example text.encode("utf-8").
usedforsecurityKeyword-only. Leave the default True for algorithms that are still appropriate as cryptographic hashes. Official documentation uses False to allow a blocked or insecure algorithm for a non-security checksum.

Returns: The constructor returns a hash object. hexdigest returns a str of hexadecimal digits. digest returns bytes. copy returns a new hash object with the same state.

Raises

  • TypeError — Raised when a str is passed where bytes are required. The measured message on Python 3.13.12 is "Strings must be encoded before hashing".
  • The TypeError message was measured on Python 3.13.12.
python
import hashlib

digest = hashlib.sha256(b"abc")
print(digest.hexdigest())
chunked = hashlib.sha256()
chunked.update(b"ab")
chunked.update(b"c")
print(chunked.hexdigest() == digest.hexdigest())
clone = hashlib.sha256(b"ab")
copied = clone.copy()
clone.update(b"c")
print(copied.hexdigest() == hashlib.sha256(b"ab").hexdigest())
try:
    hashlib.sha256("abc")
except TypeError as err:
    print(type(err).__name__, err)

Expected output

ba7816bf8f01cfea414140de5dae2223b00361a396177a9cb410ff61f20015ad
True
True
TypeError Strings must be encoded before hashing

Official documentation →

MD5 as a non-security checksum

MD5 still exists for interoperability and checksums, but it is not a modern security hash. hashlib.md5(..., usedforsecurity=False) documents that the call is not a security use. The hex digest of b"abc" is the classic test vector 900150983cd24fb0d6963f7d28e17f72. Do not treat this as password hashing, signature, or an access-control check.

hashlib.md5

hashlib.md5(data=b'', *, usedforsecurity=True)

Compute an MD5 checksum of bytes when you need the historical algorithm, and mark it as a non-security use.

ParameterDescription
dataBytes to hash, not str.
usedforsecurityPass False when MD5 is used only as a checksum. Official documentation describes this flag as allowing an insecure or blocked algorithm for non-cryptographic use.

Returns: A hash object. hexdigest returns the 32-character hexadecimal MD5 digest.

  • For key derivation, official documentation provides hashlib.pbkdf2_hmac and hashlib.scrypt. Those APIs still need a unique salt and a suitable work factor. This page does not show a copy-paste password store.
python
import hashlib

print(hashlib.md5(b"abc", usedforsecurity=False).hexdigest())

Expected output

900150983cd24fb0d6963f7d28e17f72

Official documentation →