hashlib: new() Is Case-Insensitive, Except for blake2b/blake2s (tested)

hashlib.new(name) looks like it should treat an algorithm name the same regardless of case or whether you use a hyphen or underscore -- and for most algorithms, it does. We measured whether that leniency is universal, the kind of thing that matters if an algorithm name is read from a config file, environment variable, or API parameter rather than hardcoded.

1. Most algorithm names are case- and separator-insensitive

import hashlib

for name in ("sha256", "SHA256", "sha3-256", "SHA3-256", "sha3_256"):
    h = hashlib.new(name, b"x")
    print(name, "->", h.name)
sha256 -> sha256
SHA256 -> sha256
sha3-256 -> sha3_256
SHA3-256 -> sha3_256
sha3_256 -> sha3_256

Measured: hashlib.new() accepts sha256/SHA256 and sha3-256/SHA3-256/sha3_256 interchangeably, normalizing all of them to the same underlying algorithm. This leniency comes from OpenSSL's name lookup, which most of hashlib's named constructors are backed by.

2. blake2b/blake2s break that pattern -- they're case-sensitive

import hashlib

print(hashlib.new("blake2b", b"x").name)
try:
    hashlib.new("BLAKE2B", b"x")
except Exception as e:
    print("BLAKE2B ->", type(e).__name__, e)
blake2b
BLAKE2B -> ValueError: unsupported hash type BLAKE2B

Measured: lowercase blake2b works fine, but uppercase BLAKE2B raises ValueError: unsupported hash type. Unlike the OpenSSL-backed algorithms, blake2b/blake2s have their own dedicated constructors in hashlib (hashlib.blake2b/hashlib.blake2s) and the generic new() dispatch for them does an exact string match rather than going through OpenSSL's case-insensitive name table. If an algorithm name arrives from outside your program -- a config value, an environment variable, a value copied from documentation that happens to use a different case -- most algorithms tolerate the mismatch silently, but blake2b/blake2s do not.

3. The fix: normalize to lowercase, or call the dedicated constructor directly

import hashlib

name = "BLAKE2B"
h = hashlib.new(name.lower(), b"x")
print(h.name)

# or, if you know it's blake2, skip new() entirely:
h2 = hashlib.blake2b(b"x")
print(h2.name)
blake2b
blake2b

Measured: lowercasing the name before calling hashlib.new() works for every algorithm including blake2b/blake2s, and is the safer default if the name comes from outside your code -- don't rely on new()'s case tolerance being universal just because it holds for the common SHA family.

Frequently asked questions

Is hashlib.new() case-insensitive for all algorithm names in Python?

No -- we measured hashlib.new() accepting SHA256, sha3-256, and SHA3-256 interchangeably with their lowercase/underscore forms, but hashlib.new('BLAKE2B') raised ValueError while hashlib.new('blake2b') worked fine.

Why does hashlib.new('BLAKE2B') raise an error in Python?

Because blake2b/blake2s are dispatched to their own dedicated constructors inside hashlib rather than going through OpenSSL's case-insensitive name lookup that backs algorithms like sha256 and sha3-256 -- we confirmed the exact-case match requirement by testing both forms directly.

Does hashlib.new() accept both hyphens and underscores in algorithm names?

For OpenSSL-backed algorithms, yes -- we measured sha3-256, sha3_256, and SHA3-256 all resolving to the same algorithm object with hashlib.new(). This does not extend to blake2b/blake2s, which only match their exact lowercase name.

How do I safely pass a hashlib algorithm name from user input or config?

Lowercase it before calling hashlib.new() -- we confirmed name.lower() works correctly for every algorithm we tested, including blake2b/blake2s, removing the case-sensitivity inconsistency entirely.

Can I avoid hashlib.new()'s case-sensitivity inconsistency for blake2b?

Yes -- call hashlib.blake2b() directly instead of going through hashlib.new('blake2b') if you already know which algorithm you need; we confirmed both produce an identical hash object when the name case is correct.

Written with AI assistance. Measured on 2026-10-04 with Python 3.13.5's built-in hashlib module: called hashlib.new() with several algorithm names in varying case and with hyphens vs underscores (sha256, SHA256, sha3-256, SHA3-256, sha3_256) and compared against blake2b in both lowercase and uppercase. PlainHeaders is our extension; Python's hashlib module is built in.