Python hashlibの使い方｜SHA256・MD5とファイルのハッシュ値

hashlibとは、SHA-256やMD5などのハッシュ値を計算するPythonの標準ライブラリで、hashlib.sha256(バイト列).hexdigest() と書くだけで16進数のハッシュ値が得られます。 ハッシュ値は、データから計算される固定長の値です。同じデータからは必ず同じ値になり、1バイトでも違えばまったく別の値になるので、ファイルが同じかどうかの確認や、ダウンロードしたファイルの検証に使われます。

この記事では、文字列・バイト列・ファイルの3パターンをコピペで動く形で示し、大きなファイル向けのチャンク読みと Python 3.11 で追加された hashlib.file_digest を時間とメモリで比べます。アルゴリズムの早見表、base64 への変換、sha256sum コマンドとの突き合わせ、hmac、パスワード用途での注意まで扱います。掲載した出力は Python 3.11.15（OpenSSL 3.0.13、Linux）で実際に動かした結果です。

hashlibの早見表

渡すのは必ず bytes です。str はそのまま渡せないので .encode("utf-8") で変換します。

パターン1：バイト列のハッシュ値を求める

import hashlib

print(hashlib.sha256(b"hello").hexdigest())
print(hashlib.md5(b"hello").hexdigest())

2cf24dba5fb0a30e26e83b2ac5b9e29e1b161e5c1fa7425e73043362938b9824
5d41402abc4b2a76b9719d911017c592

流れは「ハッシュオブジェクトを作る → 結果を取り出す」の2段階です。取り出し方は2つあります。

データを分けて渡すこともできます。update() を何回かに分けて呼んでも、まとめて渡したときと同じ値になります。 これが、後で出てくるファイルのチャンク読みの土台です。

import hashlib

h = hashlib.sha256()
h.update(b"hel")
h.update(b"lo")
print(h.hexdigest() == hashlib.sha256(b"hello").hexdigest())

True

パターン2：文字列のハッシュ値を求める

文字列は encode() でバイト列に変えてから渡します。

import hashlib

text = "こんにちは"
print(hashlib.sha256(text.encode("utf-8")).hexdigest())

125aeadf27b0459b8760c13a3d80912dfa8a81a68261906f60d87f4a0268646c

strをそのまま渡すとTypeErrorになる

import hashlib

hashlib.sha256("hello")

TypeError: Strings must be encoded before hashing

h.update("hello") でも同じメッセージが出ます。直し方は "hello".encode("utf-8") か、リテラルなら b"hello" にすることです。

文字コードと改行でハッシュ値は変わる

ハッシュ値はバイト列から計算されるので、同じ文字でも文字コードが違えば別の値になります。「日本語」という3文字で確かめました（先頭16文字のみ表示）。

改行の有無でも変わります。

ほかのツールや他言語と値が合わないときは、まず文字コードと末尾の改行を確認すると早く解決します。

パターン3：ファイルのハッシュ値を求める

ファイルは必ずバイナリモード（"rb"）で開きます。書き方は3通りあります。

# filehash.py
import hashlib
import sys
import time
import tracemalloc


def hash_read_all(path):
    """1. 全部読んでから計算（小さいファイル向け）"""
    with open(path, "rb") as f:
        return hashlib.sha256(f.read()).hexdigest()


def hash_chunks(path, chunk_size=1024 * 1024):
    """2. 1MiBずつ読んで update（Python 3.8以降）"""
    h = hashlib.sha256()
    with open(path, "rb") as f:
        while chunk := f.read(chunk_size):
            h.update(chunk)
    return h.hexdigest()


def hash_file_digest(path):
    """3. hashlib.file_digest（Python 3.11以降）"""
    with open(path, "rb") as f:
        return hashlib.file_digest(f, "sha256").hexdigest()


if __name__ == "__main__":
    path = sys.argv[1]
    for func in (hash_read_all, hash_chunks, hash_file_digest):
        tracemalloc.start()
        start = time.perf_counter()
        digest = func(path)
        elapsed = time.perf_counter() - start
        _, peak = tracemalloc.get_traced_memory()
        tracemalloc.stop()
        print(f"{func.__name__:17} {digest[:16]}... {elapsed:.3f}s peak={peak / 1024 / 1024:.1f}MiB")

tracemalloc は Python が確保したメモリの最大値を測るための標準ライブラリで、比較のために入れています。普段使うときは3つの関数だけを取り出してください。

小さいファイルで3つの結果が同じことを確かめる

中身が hello と改行だけの hello.txt（6バイト）で実行します。

printf 'hello\n' > hello.txt
python filehash.py hello.txt

hash_read_all     5891b5b522d5df08... 0.000s peak=0.0MiB
hash_chunks       5891b5b522d5df08... 0.000s peak=1.0MiB
hash_file_digest  5891b5b522d5df08... 0.000s peak=0.3MiB

3つとも同じ値です。

200MBのファイルで時間とメモリを比べる

209,715,200 バイト（200MiB）のファイルを作って実行した結果です（2回目の計測）。

hash_read_all     bf375859eeb4cfaf... 0.262s peak=200.0MiB
hash_chunks       bf375859eeb4cfaf... 0.177s peak=2.0MiB
hash_file_digest  bf375859eeb4cfaf... 0.185s peak=0.3MiB

全部読む方法は、ファイルの大きさと同じだけメモリを使います。 チャンク読みと file_digest は、ファイルがどれだけ大きくてもメモリの使用量がほぼ一定でした。時間は計測のたびに少し変わりますが、この環境ではチャンク読みと file_digest のほうが短くなりました（数値は環境によって変わります）。

file_digestの使い方と注意点

hashlib.file_digest(fileobj, digest, /) は Python 3.11 で追加された関数です（公式ドキュメントの hashlib のページで確認）。2つ目の引数には、アルゴリズム名の文字列か、ハッシュオブジェクトを返す関数を渡せます。

import hashlib
import io

with open("hello.txt", "rb") as f:
    print(hashlib.file_digest(f, "sha256").hexdigest())

with open("hello.txt", "rb") as f:
    print(hashlib.file_digest(f, lambda: hashlib.blake2b(digest_size=16)).hexdigest())

# ファイルでなくても、バイナリを読めるオブジェクトなら渡せる
print(hashlib.file_digest(io.BytesIO(b"hello\n"), "md5").hexdigest())

5891b5b522d5df086d0ff0b110fbd9d21bb4fc7163af34d08286a2e846f6be03
ea41b4de6c03f13a95758b28dd75693e
b1946ac92492d2347c6235b4d2611184

テキストモードで開いたファイルを渡すと、次のエラーになります。

with open("hello.txt") as f:          # "rb" を付けていない
    hashlib.file_digest(f, "sha256")

ValueError: '<_io.TextIOWrapper name='hello.txt' mode='r' encoding='utf-8'>' is not a file-like object in binary reading mode.

open(path, "rb") に直せば解決します。 テキストモードは改行の変換や文字コードの解釈が入るため、ファイルのハッシュ値には必ずバイナリモードを使います。

Python 3.10以前でも動く書き方

:=（代入式）が使えない 3.7 以前も含めて動かしたい場合は、iter を使った形にします。次のコードは 3.11 で実行して、上と同じ値になることを確かめています。

import hashlib
from functools import partial


def hash_chunks_compat(path, chunk_size=1024 * 1024):
    h = hashlib.sha256()
    with open(path, "rb") as f:
        for chunk in iter(partial(f.read, chunk_size), b""):
            h.update(chunk)
    return h.hexdigest()


print(hash_chunks_compat("hello.txt"))

5891b5b522d5df086d0ff0b110fbd9d21bb4fc7163af34d08286a2e846f6be03

アルゴリズム早見表（出力長・安全性・用途）

b"hello" を各アルゴリズムで計算し、出力の長さを実測しました。

出力長と文字数は実測値です。安全性の欄は一般に知られた評価を短くまとめたもので、今回あらためて検証したものではありません。

選び方の目安は次のとおりです。

MD5とSHA-1はどこまで使えるか

MD5 と SHA-1 は、同じハッシュ値になる別のデータを意図的に作る方法が知られています。 そのため、「誰かが中身をすり替えていないか」を確かめる用途や電子署名には、SHA-256 以降を選びます。

一方で、通信やコピーの途中で偶然ビットが変わっていないかを確かめる用途や、手元のフォルダから同じ内容のファイルを探す用途では、今も広く使われています。「意図的なすり替えを防ぎたいかどうか」が判断の分かれ目です。

セキュリティ目的ではないことを明示する引数もあります。

import hashlib

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

5d41402abc4b2a76b9719d911017c592

usedforsecurity は Python 3.9 で追加されたキーワード専用引数で、既定値は True です（公式ドキュメントで確認）。MD5 の利用が制限された環境でも、False を指定するとセキュリティ以外の目的として計算できる場合があります。

使えるアルゴリズムを調べる

import hashlib

print(sorted(hashlib.algorithms_guaranteed))
print(sorted(hashlib.algorithms_available - hashlib.algorithms_guaranteed))

['blake2b', 'blake2s', 'md5', 'sha1', 'sha224', 'sha256', 'sha384', 'sha3_224', 'sha3_256', 'sha3_384', 'sha3_512', 'sha512', 'shake_128', 'shake_256']
['md5-sha1', 'ripemd160', 'sha512_224', 'sha512_256', 'sm3']

2行目のように OpenSSL 由来のものは、hashlib.new("名前", データ) で使います。存在しない名前を渡すと次のようになります。

hashlib.new("sha999")

ValueError: unsupported hash type sha999

hexdigestとbase64出力を変換する

API の仕様によっては、ハッシュ値を16進数ではなく base64 で渡すよう求められます。ポイントは、hexdigest() の文字列ではなく digest() のバイト列を base64 にすることです。

import base64
import hashlib

d = hashlib.sha256(b"hello").digest()
print(type(d), len(d))
print(d.hex())                                   # hexdigest() と同じ
print(base64.b64encode(d).decode())              # 標準の base64
print(base64.urlsafe_b64encode(d).decode())      # URL に入れられる形
print(base64.urlsafe_b64encode(d).rstrip(b"=").decode())  # 末尾の = を外した形

<class 'bytes'> 32
2cf24dba5fb0a30e26e83b2ac5b9e29e1b161e5c1fa7425e73043362938b9824
LPJNul+wow4m6DsqxbninhsWHlwfp0JecwQzYpOLmCQ=
LPJNul-wow4m6DsqxbninhsWHlwfp0JecwQzYpOLmCQ=
LPJNul-wow4m6DsqxbninhsWHlwfp0JecwQzYpOLmCQ

16進数とbase64を相互に変換する

import base64
import hashlib

hex_value = hashlib.sha256(b"hello").hexdigest()

# 16進数 → base64
b64_value = base64.b64encode(bytes.fromhex(hex_value)).decode()
print(b64_value)

# base64 → 16進数
print(base64.b64decode(b64_value).hex())

LPJNul+wow4m6DsqxbninhsWHlwfp0JecwQzYpOLmCQ=
2cf24dba5fb0a30e26e83b2ac5b9e29e1b161e5c1fa7425e73043362938b9824

うまくいかない例：16進数の文字列をそのままbase64にする

hex_value = hashlib.sha256(b"hello").hexdigest()
print(base64.b64encode(hex_value.encode()).decode())

MmNmMjRkYmE1ZmIwYTMwZTI2ZTgzYjJhYzViOWUyOWUxYjE2MWU1YzFmYTc0MjVlNzMwNDMzNjI5MzhiOTgyNA==

88文字の別の値になりました。これは「64文字のテキスト」を base64 にした結果です。相手の仕様が「SHA-256 の base64」なら 44文字になるはずなので、長さを見ると取り違えに気づけます。

sha256sum・certutil・Get-FileHashと突き合わせる

Python で計算した値は、OS のコマンドの結果と一致します。hello.txt で確かめました。

Linux・macOS

sha256sum hello.txt
md5sum hello.txt
sha1sum hello.txt
openssl dgst -sha256 hello.txt
openssl dgst -sha256 -binary hello.txt | base64

5891b5b522d5df086d0ff0b110fbd9d21bb4fc7163af34d08286a2e846f6be03  hello.txt
b1946ac92492d2347c6235b4d2611184  hello.txt
f572d396fae9206628714fb2ce00f72e94f2258f  hello.txt
SHA2-256(hello.txt)= 5891b5b522d5df086d0ff0b110fbd9d21bb4fc7163af34d08286a2e846f6be03
WJG1tSLV3whtD/CxEPvZ0hu0/HFjrzTQgoai6Eb2vgM=

Python の hashlib.file_digest(f, "sha256").hexdigest() の結果 5891b5b5...6be03 と同じ値です。macOS では shasum -a 256 hello.txt が同じ役割を持ちます（macOS では未実行）。

Windows

Windows のコマンドは今回の検証環境（Linux）では未実行です。一般に知られた書き方を載せます。

# コマンドプロンプト・PowerShell のどちらでも
certutil -hashfile hello.txt SHA256

# PowerShell
Get-FileHash hello.txt -Algorithm SHA256

Get-FileHash は16進数を大文字で表示することが知られています。大文字と小文字の違いで不一致と判定しないよう、比べる前に .lower() でそろえておくと確実です。

公開されているハッシュ値と照合するコード

import hashlib
import hmac

expected = "5891B5B522D5DF086D0FF0B110FBD9D21BB4FC7163AF34D08286A2E846F6BE03"

with open("hello.txt", "rb") as f:
    actual = hashlib.file_digest(f, "sha256").hexdigest()

if hmac.compare_digest(actual, expected.lower()):
    print("一致しました")
else:
    print("一致しません")

一致しました

同じ内容のファイルを探すコード

import hashlib
from pathlib import Path

seen = {}
for p in sorted(Path(".").glob("*.txt")):
    with p.open("rb") as f:
        digest = hashlib.file_digest(f, "sha256").hexdigest()
    seen.setdefault(digest, []).append(p.name)

for digest, names in seen.items():
    print(digest[:12], names)

hello.txt とそのコピー copy.txt、内容の違う other.txt を置いて実行した結果です。

5891b5b522d5 ['copy.txt', 'hello.txt']
abc6fd595fc0 ['other.txt']

hmacで鍵つきハッシュを作り、compare_digestで比べる

ハッシュ値だけでは「誰が作ったか」は分かりません。送り手と受け手だけが知る鍵を混ぜて計算するのが HMAC で、Webhook の署名検証などで使われます。標準ライブラリの hmac モジュールで計算します。

import hashlib
import hmac

key = b"secret-key"
message = b"order_id=1001&amount=3"

signature = hmac.new(key, message, hashlib.sha256).hexdigest()
print(signature)

# 受け取った署名と、自分で計算した署名を比べる
print(hmac.compare_digest(signature, signature))
print(hmac.compare_digest(signature, "0" * 64))

652b9002c59241e37ab133694621636c9f6feddaba6d0c16ddb2b6cc12fb3b48
True
False

署名・トークン・パスワード由来の値を比べるときは hmac.compare_digest を使う、と覚えておくと安心です。 引数は str 同士か bytes 同士でそろえます。

鍵と sha256(鍵 + メッセージ) のように自分でつなげる方法より、hmac を使うほうが確実です。HMAC は、つなげ方に由来する弱点が出ないように設計された方式だからです。

BLAKE2 は、key 引数だけで鍵つきハッシュを計算できます。

import hashlib

print(hashlib.blake2b(b"hello", digest_size=16).hexdigest())
print(hashlib.blake2b(b"hello", key=b"secret-key", digest_size=16).hexdigest())

46fb7408d4f285228f4af516ea25851b
b1fb20c57a78318a65275be0730592bc

パスワードにはscryptやpbkdf2_hmacを使う理由

SHA-256 は速く計算できることを目指して作られています。この環境で hashlib.sha256(b"correct horse").digest() を100万回繰り返すと、0.511秒で終わりました。ファイルの検証にはうれしい性質ですが、パスワードの保存では、保存した値が外に出たときに、候補を次々に試す総当たりも同じ速さでできてしまいます。

そこで、わざと時間とメモリを使う専用の関数（鍵導出関数）を使います。hashlib には2つ入っています。

import hashlib
import time

salt = bytes.fromhex("00112233445566778899aabbccddeeff")  # 説明用の固定値

start = time.perf_counter()
dk = hashlib.pbkdf2_hmac("sha256", b"correct horse", salt, 600_000)
print("pbkdf2", dk.hex(), round(time.perf_counter() - start, 3))

start = time.perf_counter()
dk = hashlib.scrypt(b"correct horse", salt=salt, n=2**14, r=8, p=1, dklen=32)
print("scrypt", dk.hex(), round(time.perf_counter() - start, 3))

pbkdf2 c86dc9e58e15a00450c9f7d3310c51a16b77142b24de7ac79c735ea118c5cf50 0.265
scrypt f5206d570fcd120bd1f23a8cd186bd87c04ac1db00e9ac1efca589774ae6ecb8 0.056

正しい利用者のログインは1回の計算で済むので 0.1〜0.3 秒は気になりませんが、総当たりには大きな差になります。 これが専用の関数を使う理由です。

シグネチャと推奨の記述は、公式ドキュメントの hashlib のページで確認しました。

ソルトつきで保存し、照合するコード

ソルトは、パスワードごとに付ける乱数です。同じパスワードでも保存される値が毎回変わるので、あらかじめ計算した一覧表との突き合わせを防げます。

import hashlib
import hmac
import os


def hash_password(password: str) -> str:
    salt = os.urandom(16)
    dk = hashlib.scrypt(password.encode("utf-8"), salt=salt, n=2**14, r=8, p=1, dklen=32)
    return f"scrypt$16384$8$1${salt.hex()}${dk.hex()}"


def verify_password(password: str, stored: str) -> bool:
    _, n, r, p, salt_hex, dk_hex = stored.split("$")
    dk = hashlib.scrypt(
        password.encode("utf-8"),
        salt=bytes.fromhex(salt_hex),
        n=int(n), r=int(r), p=int(p), dklen=32,
    )
    return hmac.compare_digest(dk, bytes.fromhex(dk_hex))


stored = hash_password("correct horse")
print(len(stored))
print(verify_password("correct horse", stored), verify_password("wrong", stored))
print(hash_password("correct horse") == stored)

114
True False
False

最後の False は、同じパスワードでもソルトが違うので保存値が変わることを示しています。パラメータ（n, r, p）を一緒に保存しておくと、後から強度を上げるときに以前の値も照合できます。

scrypt の n を大きくしすぎると、既定のメモリ上限に当たります。

hashlib.scrypt(b"p", salt=salt, n=2**20, r=8, p=1)

ValueError: [digital envelope routines] memory limit exceeded

この場合は maxmem 引数で上限を広げるか、n を見直します。

Web アプリケーションのログイン機能では、bcrypt や Argon2 を扱う専用ライブラリを使うことも多くあります。ここでは「標準ライブラリだけで作るなら scrypt か pbkdf2_hmac」と押さえておけば十分です。

つまずきやすい点と直し方

よくある質問

Q. hexdigest() と digest() はどちらを使えばよいですか？ A. 画面表示やログ、テキストでの受け渡しには hexdigest() が向いています。base64 にしたい、バイナリのまま保存したい、HMAC の比較に使いたい、という場合は digest() を使います。

Q. ハッシュ値から元のデータに戻せますか？ A. 戻せません。ハッシュは一方向の計算です。元に戻せる必要があるなら、暗号化という別の技術を使います。base64 は見た目を変えるだけの変換なので、ハッシュとも暗号化とも役割が違います。

Q. Python 組み込みの hash() 関数との違いは何ですか？ A. hash() は辞書や集合の内部で使うための値で、文字列に対してはプロセスを起動するたびに結果が変わります。ファイルの検証や保存には、毎回同じ値になる hashlib を使います。

Q. チャンクの大きさはいくつにすればよいですか？ A. 64KiB〜1MiB 程度がよく使われます。この記事では 1MiB で、200MiB のファイルを 0.177秒・最大 2.0MiB のメモリで計算できました。3.11 以降なら file_digest に任せると、大きさを考えずに済みます。

まとめ

• hashlib に渡すのは bytes。文字列は .encode("utf-8")、ファイルは "rb" で開く
• ファイルは 3.11 以降なら hashlib.file_digest、それ以前はチャンク読み。200MiB のファイルでもメモリは数MiB以内に収まった
• 迷ったら SHA-256。MD5 と SHA-1 は破損チェックや重複検出、既存の仕組みとの互換に使う
• base64 にするのは digest() のバイト列。SHA-256 なら 44文字になる
• sha256sum や openssl dgst の結果と一致することを実行して確かめた（Windows のコマンドは未実行）
• 署名やトークンの比較は hmac.compare_digest、鍵つきハッシュは hmac モジュール
• パスワードには scrypt や pbkdf2_hmac。わざと時間をかけることで総当たりを難しくする

株式会社RJCでは、Pythonのハッシュ計算の使い方を仲間と学び合っています。こうした知識を共有しながら、日々技術を磨いています。

株式会社RJC ― SI事業・SES事業・AI駆動開発。RJCは一緒に成長を楽しめる会社です。