GGUF (GGML Universal File Format)
Self-contained binary model weight format for llama.cpp and local LLM inference engines, storing architecture KV metadata, BPE vocabulary, and quantized tensor blocks in a single mmap-ready file.
GGUF v3 starts with 'GGUF' magic, version, 64-bit tensor_count, and metadata_kv_count. Because metadata_kv embeds full 128K+ token arrays before tensor_infos, client-side parsers must page through chunks rather than slicing a fixed 64 KB.
Drop any .gguf file (even 100 GB+) to inspect locally
Reads tiny File.slice() header/footer pages in a sandboxed Web Worker · 0 Bytes Uploaded
.gguf Magic Bytes & Header Offset Map
GGUF 4-byte ASCII magic signature
| Byte Offset | Length | Data Type | Field Name | Engineering Description |
|---|---|---|---|---|
| 0x00 - 0x03 | 4 B | char[4] | magic | Fixed ASCII magic 'GGUF' (0x46554747 LE) |
| 0x04 - 0x07 | 4 B | uint32_le | version | Format version (v2 or v3 in production) |
| 0x08 - 0x0F | 8 B | uint64_le | tensor_count | Number of tensor descriptors following KV section |
| 0x10 - 0x17 | 8 B | uint64_le | metadata_kv_count | Number of typed metadata key-value entries |
.gguf Security & Polyglot Risk Matrix
Verify 0x00=='GGUF', version in {2,3}, and enforce sane upper bounds on uint64 string/array lengths to prevent integer-overflow OOM in C++ parsers.
Read .gguf Header & Metadata Without Heavy Dependencies
import struct, sys
with open(sys.argv[1], "rb") as f:
magic, ver, n_tensors, n_kv = struct.unpack("<4sIQQ", f.read(24))
assert magic == b"GGUF", f"Invalid magic: {magic}"
print(f"GGUF v{ver}: {n_tensors} tensors, {n_kv} metadata KV pairs")Deterministic .gguf Sample Files & Edge Cases
minimal-llama.gguf
Compact GGUF v3 binary with Llama architecture KV metadata, 8-token vocabulary array, and 2 aligned tensors (F16 & Q8_0).
curl -fsSL https://fileformat.co/fixtures/v1/gguf/minimal-llama.gguf -o minimal-llama.gguf \
&& echo "2ec356e162053c781631412e0ef64fe4672618855458afc781eff05dbda10a5d minimal-llama.gguf" | shasum -a 256 -cllama3-tiny.gguf
Rich GGUF v3 model fixture with RoPE/GQA hyperparameters, multilingual/emoji tokenizer table, and F32/F16/Q8_0/Q4_K tensor descriptors.
curl -fsSL https://fileformat.co/fixtures/v1/gguf/llama3-tiny.gguf -o llama3-tiny.gguf \
&& echo "1e9c572f8666905c15ab3bd03689a613980af4547600b7eeccde39a387424044 llama3-tiny.gguf" | shasum -a 256 -ctruncated-metadata.gguf
Negative test fixture claiming 6 tensors and 14 KV entries but truncated at 112 bytes to verify parser bounds checking.
curl -fsSL https://fileformat.co/fixtures/v1/gguf/truncated-metadata.gguf -o truncated-metadata.gguf \
&& echo "81fec5725175f7820eaebf9d3ddcc53edb19595f60f24e73a29ef13731e032c9 truncated-metadata.gguf" | shasum -a 256 -cRelated Specifications & Alternatives
Hugging Face's memory-safe, zero-copy tensor serialization format designed to replace Pickle-based PyTorch checkpoints without arbitrary code execution risks.
Cross-framework Protocol Buffers computation graph and weight format used by ONNX Runtime, TensorRT, and CoreML converters.
Default PyTorch `torch.save()` archive wrapping a Python Pickle instruction stream (`data.pkl`) alongside raw tensor storage files inside a ZIP container.