openai/whisper · error · RuntimeError

Model has been downloaded but the SHA256 checksum does not…

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'.)

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

• 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.

Appendix: 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)