Concepts
Verification
The one rule that makes a download from anywhere safe, and the three ways to apply it.
MarkdownA file you downloaded is only as trustworthy as the host that served it, unless you already knew what its bytes should hash to. The hub gives you that number before you fetch anything.
The rule
Hash what arrives. Keep the file only if its hash equals the value the tree gave you: the SHA-256 in lfs.oid for a large file, the git blob SHA-1 in oid for a small one. The expected hash comes from the tree and never from the source that served the bytes.
The hub does not verify on read. It cannot: the bytes never pass through it. Verification happens on your machine, or inside a client that does it for you.
Where the expected hash comes from
| Dialect | Field | Source of truth |
|---|---|---|
| Hugging Face Hub API | lfs.oid (SHA-256, large files) and oid (git blob SHA-1, every file) in /api/models/<owner>/<name>/tree/main |
the tree, exactly as Hugging Face publishes it |
SHA256SUMS under /via/<source>/ |
one line per file, in sha256sum format |
generated by the hub from the index; never redirected |
| OCI | each layer's digest in the manifest |
the index; a layer is one raw file, so its digest is the file's SHA-256 |
| Ollama | the layer digests Ollama checks itself | the index |
| Objects | files[].sha256 in the model object |
the object, whose own address is the BLAKE3 of its bytes |
The Etag on a /resolve/ redirect is the same hash the tree names, quoted. It is a convenience, not a second source.
Check one file
curl -sL https://gethologram.ai/hexgrad/Kokoro-82M/resolve/main/EVAL.md -o EVAL.md
git hash-object --no-filters EVAL.md
484ac8dcd971465258007528fb8bc4a99cf98633
That equals oid for EVAL.md in the tree. Git's blob SHA-1 is SHA-1 over blob <size>, a zero byte, then the bytes, so any SHA-1 tool can compute it. For a large file, sha256sum the bytes and compare with lfs.oid.
Check a whole download
After hf download, with Hugging Face's own tool:
hf cache verify hexgrad/Kokoro-82M
It hashes every cached file against the tree, large files by SHA-256 and small ones by git blob SHA-1, and exits non-zero on any mismatch, so it works as a gate in a script. Files you did not download are reported as missing, not failed; add --fail-on-missing-files to make them fail too.
Clients that check for you
| Client | What it checks | What you do |
|---|---|---|
| Ollama | the SHA-256 of every layer, before the model is usable | nothing |
| oras, modctl, skopeo, crane, containerd | every blob against its digest | nothing |
huggingface_hub |
the size it was told to expect; not the hash | hf cache verify <owner>/<name> |
curl |
nothing | sha256sum or git hash-object --no-filters, compared with the tree |
On a mismatch
Drop the file and fetch it again from another source: put /via/ipfs or /via/modelscope in front of the path. The expected hash does not change; only the source does. If every source disagrees with the index, the index is wrong for that file, and the hub wants to know: use POST /api/account/request from a signed-in account, or open an issue on the repository.
Check an object
Objects are addressed by BLAKE3, not SHA-256. The address you asked for must equal the BLAKE3 of the bytes you received. With the blake3 Python package:
curl -s https://gethologram.ai/api/v1/objects/blake3:3cc11e52049117dfc397240fddc7a4d3aa392ded7f623986e4e5757371363d9e -o model.json
python3 -c "from blake3 import blake3; print(blake3(open('model.json','rb').read()).hexdigest())"
3cc11e52049117dfc397240fddc7a4d3aa392ded7f623986e4e5757371363d9e
The Objects page explains what that object is.