Ollama blob digests: verify a model file before you load it

tutorialworkflowtroubleshooting

TL;DR: Ollama treats every model layer as a content-addressed blob named by its SHA256 digest. The upstream API exposes three integrity checks you can run without a GPU: GET /api/tags returns the digest and size of every installed model, HEAD /api/blobs/:digest answers whether a blob is already on the server, and POST /api/blobs/:digest makes the server hash the file you upload and reject it with 400 Bad Request when the digest does not match. The pull stream itself prints a literal verifying sha256 digest status before it writes the manifest.

What you’ll be able to do:

  • Tell a model digest apart from a file digest, so you do not compare two numbers that were never the same kind of number.
  • Verify a GGUF or safetensors file you downloaded yourself against a published SHA256 before it enters your model library.
  • Detect a truncated or partially written layer before it turns into an unexplained load failure.
  • Re-use one check script instead of writing a new ad-hoc verification for every model you import.

Honest take: If your model loads and answers, the digest check is unnecessary. It matters at the moment a model is not loading and the error message points nowhere — a half-written 20 GB layer looks exactly like a bad install from the outside.

Why verify a digest before loading a model?

A local model library is a directory of large binary files that arrive over the network, get written to disk, and are then loaded into VRAM. Three different things can go wrong in that chain, and only one of them produces an error message that names the real problem:

  1. The download stopped early. The layer file is present but shorter than the manifest says it should be.
  2. The bytes changed on the way to disk. A proxy, a mirror, or a bug in the tool rewrote the file.
  3. The file on disk is fine, but it is the wrong file. You imported a different quantization than you meant to.

In every one of those cases the symptom at load time is the same — an error about a missing tensor, a header mismatch, or a model that fails to start — and none of those messages tell you “the layer is 4 GB short”. Checking the digest before the load moves the diagnosis to the step where the answer is still cheap.

Ollama’s upstream API specification, checked November 15, 2026, documents the digest as a first-class part of the protocol: POST /api/pull streams a digest field for every layer it downloads, GET /api/tags returns a digest and a size for every installed model, and the blob endpoints take a SHA256 digest as their URL parameter. The server also reports a verifying sha256 digest status during a pull, confirmed in the same upstream API documentation and in the server source at server/images.go.

This verification needs no GPU, no model inference, no weight download, and no paid API. It proves that the bytes on disk match the digest they were published under. It does not prove that the model is the one you wanted, that it will fit in your VRAM, or that it produces good answers.

Which endpoints answer which integrity question?

Three documented endpoints cover the whole check. They answer different questions, and mixing them up is the most common reason a “verification” script produces a confident wrong answer.

EndpointMethodQuestion it answersSuccess signalFailure signal
/api/tagsGETWhich models are installed, and what digest does the server report for each?JSON list with name, size, digest per model404 if the server is not reachable at that address
/api/blobs/:digestHEADIs this exact blob already stored on this server?200 OK404 Not Found
/api/blobs/:digestPOSTDoes the file I am uploading hash to the digest in the URL?201 Created400 Bad Request when the digest is not the expected one

The POST form is the interesting one. The upstream documentation states plainly: “Return 201 Created if the blob was successfully created, 400 Bad Request if the digest used is not expected.” The server hashes what you send and compares it against the digest you claimed. That makes the local server an integrity checker for any file you want to import — you do not need to trust your own hashing tool to be the only opinion in the room.

What does the pull stream actually report?

A pull is a stream of JSON objects, not one response, and the statuses tell you how far the download got. The upstream API documentation shows the exact sequence:

  1. {"status":"pulling manifest"} — the manifest is being fetched.
  2. One downloading object per layer, each with status, digest, total, and completed. Until a layer finishes, the completed key may be missing.
  3. {"status":"verifying sha256 digest"} — the server checks the downloaded bytes.
  4. {"status":"writing manifest"} — the local manifest is written.
  5. {"status":"removing any unused layers"} — stale layers are cleaned up.
  6. {"status":"success"} — done.

The order matters for diagnostics. The manifest is written after the verification step, so a model that appears in /api/tags with a valid digest has already passed the server’s own hash check. If a pull ends without success, the model is not registered as complete, and the layers that were already on disk may be sitting there unreferenced until the next successful pull or a manual cleanup.

If you want to keep that evidence, save the stream instead of scrolling past it:

curl -sS http://localhost:11434/api/pull \
  -d '{"model":"YOUR_MODEL_TAG"}' | tee pull-stream.ndjson

Each line is a self-contained JSON object, so the file can be parsed with a five-line Python loop. That file is also the record of which digests this specific pull claimed to fetch — useful weeks later when someone asks why the installed model differs from the one they remember downloading.

Model digest and file digest are different numbers

This is the distinction that makes naive verification scripts report false failures.

The digest in GET /api/tags identifies the model manifest, not the GGUF file inside it. The manifest is a small JSON document that lists the layers and their digests, and it is itself hashed — the upstream server source logs the manifest digest and its byte length when it writes the file. So:

  • sha256 of your model.gguf = the digest of one layer file.
  • digest from /api/tags = the digest of the manifest that points at several layer files.

Those two values will never match, and a script that compares them will report a corrupt model for every perfectly healthy install. The correct comparison is layer digest against layer digest, or file digest against the digest the source published for that file.

If you downloaded a GGUF or safetensors file yourself and want to check it before it ever reaches the model library, hash the file and compare that value with the digest published by whoever gave you the file:

sha256sum your-model-file.gguf

The upstream API documents the same idea for imports: when you create a model from safetensors files or from GGUF files, you push a blob for each file and then reference each file by its name and SHA256 digest in the files field of the create request. The digest is the identity of the file, in every step of that flow.

How do you check a file you downloaded yourself?

Two steps, and the second one makes the server check for you.

Step 1 — hash it locally. Compute the SHA256 of the file and keep the value:

sha256sum your-model-file.gguf
# or, with the Python standard library only:
python3 -c "import hashlib,sys;print(hashlib.sha256(open(sys.argv[1],'rb').read()).hexdigest())" your-model-file.gguf

Step 2 — let the server verify it. Upload the file under the digest you computed, and read the status code:

DIGEST=$(sha256sum your-model-file.gguf | cut -d' ' -f1)
curl -sS -o /dev/null -w '%{http_code}\n' \
  -X POST "http://localhost:11434/api/blobs/sha256:${DIGEST}" \
  -T your-model-file.gguf

201 means the server hashed the upload and it matched. 400 means it did not, and the file is not in your library. Before uploading a multi-gigabyte file, ask whether the blob is already there:

curl -sS -o /dev/null -w '%{http_code}\n' -I \
  "http://localhost:11434/api/blobs/sha256:${DIGEST}"

200 means the server already holds a blob with that digest, so an upload is unnecessary and the existing copy is already verified.

How can you validate a saved digest report in Python?

The script below keeps the two digest kinds apart and turns HTTP status codes into explicit verdicts. It talks to a local Ollama server over plain HTTP using only the Python standard library, and it never loads a model.

#!/usr/bin/env python3
"""Check Ollama blob digests before you trust a model file.

Verdicts:
  BLOB_PRESENT     the server already stores a blob with this digest
  BLOB_ABSENT      no blob with this digest on this server
  DIGEST_MATCH     the server hashed the uploaded file and it matched
  DIGEST_MISMATCH  the server hashed the uploaded file and rejected it
  SERVER_ERROR     the server answered something else entirely
"""
import hashlib
import json
import sys
import urllib.error
import urllib.request

DEFAULT_BASE = "http://localhost:11434"

# Local servers must not be reached through an HTTP proxy. If HTTP_PROXY is set
# in your shell (common on corporate machines and CI runners), urllib would
# route 127.0.0.1 through it and every request would fail with a proxy error.
OPENER = urllib.request.build_opener(urllib.request.ProxyHandler({}))


def file_digest(path):
    h = hashlib.sha256()
    with open(path, "rb") as fh:
        for chunk in iter(lambda: fh.read(1024 * 1024), b""):
            h.update(chunk)
    return h.hexdigest()


def head_blob(base, digest):
    req = urllib.request.Request(f"{base}/api/blobs/sha256:{digest}", method="HEAD")
    try:
        with OPENER.open(req, timeout=30) as resp:
            return resp.status
    except urllib.error.HTTPError as e:
        return e.code
    except Exception as e:  # connection refused, DNS, timeout
        reason = getattr(e, "reason", e)
        return f"error:{e.__class__.__name__}:{reason}"


def push_blob(base, digest, path):
    """The server hashes the body; 201 means the digest matched."""
    data = open(path, "rb").read()
    req = urllib.request.Request(
        f"{base}/api/blobs/sha256:{digest}",
        data=data,
        method="POST",
        headers={"Content-Type": "application/octet-stream"},
    )
    try:
        with OPENER.open(req, timeout=1800) as resp:
            return resp.status
    except urllib.error.HTTPError as e:
        return e.code
    except Exception as e:
        return f"error:{e.__class__.__name__}"


def model_digests(base):
    with OPENER.open(f"{base}/api/tags", timeout=30) as resp:
        data = json.load(resp)
    return {m["name"]: m.get("digest") for m in data.get("models", [])}


def main():
    base = DEFAULT_BASE
    args = [a for a in sys.argv[1:] if not a.startswith("--base=")]
    for a in sys.argv[1:]:
        if a.startswith("--base="):
            base = a.split("=", 1)[1]
    if not args:
        print("usage: check_blob_digest.py <model-file> [--base=URL]")
        return 2

    path = args[0]
    digest = file_digest(path)
    print(f"file       {path}")
    print(f"sha256     {digest}")

    status = head_blob(base, digest)
    if status == 200:
        print(f"verdict    BLOB_PRESENT (HEAD {status})")
        return 0
    if status == 404:
        print(f"verdict    BLOB_ABSENT (HEAD {status}) - upload it to verify")
    else:
        print(f"verdict    SERVER_ERROR (HEAD {status})")
        return 1

    status = push_blob(base, digest, path)
    if status == 201:
        print(f"verdict    DIGEST_MATCH (POST {status})")
        return 0
    if status == 400:
        print(f"verdict    DIGEST_MISMATCH (POST {status}) - do not import this file")
        return 1
    print(f"verdict    SERVER_ERROR (POST {status})")
    return 1


if __name__ == "__main__":
    raise SystemExit(main())

The script was exercised against a local HTTP fixture that reproduces the documented status codes, using Python 3.13. The fixture returns 200 for a known digest, 404 for an unknown one, and 400 for a body whose hash does not match the digest in the URL:

Check caseConditionObserved verdictWhat it proves
File already presentHEAD for the digest the server knowsBLOB_PRESENTNo re-upload is needed; the stored blob already matches
File not presentHEAD for an unknown digestBLOB_ABSENTThe upload path is required before verification
Upload matchesPOST with a body hashing to the requested digestDIGEST_MATCHThe server’s own hash agrees with the local hash
Upload differsPOST with a body that hashes elsewhereDIGEST_MISMATCHA modified file is rejected instead of silently imported
Server unreachableConnection refused or timeoutSERVER_ERRORAn unreachable server is never reported as a verified file

These are the documented HTTP contracts exercised against a local fixture. They are not measurements of a real multi-gigabyte upload, and they say nothing about how fast your disk or network is.

Where this fits in a home-lab workflow

Digest verification is one step in a longer chain, and it is cheap enough to do every time. A sensible order for a home lab is:

  1. Hash the file you downloaded before you copy it into your model directory.
  2. Confirm the digest with the publisher’s manifest or with the server itself, as above.
  3. Import it, then confirm the tag appears in GET /api/tags with a digest and a size.
  4. Read the metadata of the installed tag with POST /api/show to confirm the quantization and context limit — the model metadata check covers that step.
  5. Size the VRAM before the first load, using the VRAM calculator and the GPU buying guide if the model does not fit what you own.

If a pull ends in an error instead of success, the pull retry and EOF troubleshooting guide covers the connection-level failures, and the Ollama memory reporting guide explains how disk size and resident VRAM differ once a model is loaded. If your weights come from a Hugging Face repository rather than an Ollama library, check the safetensors header on AIFoss first: verify a model file before loading weights.

Honest take: what a digest check cannot tell you

A matching digest proves the bytes are the bytes the publisher published. It does not prove the publisher published the right file for your hardware, and it does not prove the model will run.

  • Correct bytes, wrong job. A verified 70B model still will not fit in a 12 GB card. Digest verification is a gate on integrity, not on capacity.
  • Verified and still slow. A file that matches its digest can still be the wrong quantization for your GPU architecture, or the wrong context length for your use case.
  • Verified and still wrong model. If you hashed the wrong file correctly, the digest still matches. Only the publisher’s manifest tells you which file is the right one.
  • The server is not the registry. The upstream documentation is explicit that HEAD /api/blobs/:digest “checks your Ollama server and not ollama.com”. A 200 from your own server is a statement about your own storage, not about what is published upstream.

Use the digest check at the moment it saves you the most time: right after a large download, before a first load, and before you trust a file that came from somewhere other than the official library.

Sources

Last updated November 15, 2026. Official Ollama documentation and upstream source were checked on this date. Local verification used deterministic HTTP and file fixtures with Python 3.13, without model inference, weight downloads, hardware benchmarks, or paid API calls.

Was this article helpful?

Get the numbers before you buy

New GPU and mini-PC benchmarks, VRAM thresholds, and price checks — sent when there's something worth acting on, not on a schedule. No spam, unsubscribe anytime.