openai/whisper · error · RuntimeError

Model has been downloaded but the SHA256 checksum does not n

Error message

Model has been downloaded but the SHA256 checksum does not not match. Please retry loading the model.

What it means

After downloading a checkpoint, whisper verifies the file's SHA256 against the hash embedded in the OpenAI URL. If the freshly downloaded bytes do not hash to the expected value, the download is considered corrupt/truncated and a RuntimeError is raised. (Note the message contains a typo: 'does not not match'.)

Source

Thrown at whisper/__init__.py:91

    with urllib.request.urlopen(url) as source, open(download_target, "wb") as output:
        with tqdm(
            total=int(source.info().get("Content-Length")),
            ncols=80,
            unit="iB",
            unit_scale=True,
            unit_divisor=1024,
        ) as loop:
            while True:
                buffer = source.read(8192)
                if not buffer:
                    break

                output.write(buffer)
                loop.update(len(buffer))

    model_bytes = open(download_target, "rb").read()
    if hashlib.sha256(model_bytes).hexdigest() != expected_sha256:
        raise RuntimeError(
            "Model has been downloaded but the SHA256 checksum does not not match. Please retry loading the model."
        )

    return model_bytes if in_memory else download_target


def available_models() -> List[str]:
    """Returns the names of available models"""
    return list(_MODELS.keys())


def load_model(
    name: str,
    device: Optional[Union[str, torch.device]] = None,
    download_root: str = None,
    in_memory: bool = False,
) -> Whisper:
    """

View on GitHub (pinned to 5f86d1d863)

Solutions

1. Delete the partial file and retry: rm ~/.cache/whisper/<model>.pt && rerun load_model
2. Verify the file size against the published model size; if truncated, download manually with curl/wget --continue to the cache path and retry
3. Check disk space at the cache location (df -h ~/.cache) and free space or move download_root elsewhere
4. If behind a proxy, bypass it or configure HTTPS_PROXY correctly so the raw bytes pass through unmodified

Example fix

# before
model = whisper.load_model("large-v3")  # RuntimeError: checksum does not match

# after
import os, urllib.request, whisper
root = os.path.expanduser("~/.cache/whisper")
target = os.path.join(root, "large-v3.pt")
if os.path.exists(target):
    os.remove(target)  # drop corrupt partial download
model = whisper.load_model("large-v3")  # re-downloads cleanly

import hashlib, os, urllib.parse

def verify_cached(root, url):
    target = os.path.join(root, os.path.basename(url))
    expected = url.split("/")[-2]
    if os.path.isfile(target):
        return hashlib.sha256(open(target, "rb").read()).hexdigest() == expected
    return None  # not downloaded yet

for attempt in range(3):
    try:
        model = whisper.load_model(name)
        break
    except RuntimeError as e:
        if "SHA256" in str(e) and attempt < 2:
            os.remove(os.path.join(cache_root, f"{name}.pt"))
            continue
        raise

When it happens

Trigger: A network layer truncates or alters the download: flaky connection, an HTTP proxy that injects an error page, a corporate MITM, disk full during write, or a partially flushed read of download_target immediately after the loop closes. Raised on the second phase of _download(), after the full byte stream was written.

Common situations: Unstable Wi-Fi/VPN, docker containers with small tmpfs at the cache path, CI runners behind authenticated proxies, or cloud function execution environments (AWS Lambda) where /tmp is size-limited and the large-v3 checkpoint gets cut off.

Related errors

• {download_target} exists and is not a regular file

AI-assisted analysis of openai/whisper@5f86d1d863 (2026-08-14). Data as JSON: /api/errors/1eda16d4818b59c2. Report an issue: GitHub.