{
  "schemaVersion": "1.0",
  "canonicalPage": "https://fileformat.co/ext/gguf",
  "inspectorUrl": "https://fileformat.co/inspect",
  "spec": {
    "slug": "gguf",
    "extension": ".gguf",
    "aliases": [],
    "name": "GGUF (GGML Universal File Format)",
    "shortName": "GGUF",
    "category": "ai-ml",
    "tier": 1,
    "summary": "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.",
    "technicalNotes": "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.",
    "mimeTypes": [
      "application/octet-stream"
    ],
    "identifiers": {
      "specUrl": "https://github.com/ggerganov/ggml/blob/master/docs/gguf.md"
    },
    "binarySignature": {
      "endianness": "little",
      "magicBytes": [
        {
          "offset": 0,
          "hex": "47 47 55 46",
          "ascii": "GGUF",
          "description": "GGUF 4-byte ASCII magic signature"
        }
      ],
      "containerFamily": null,
      "headerLayout": [
        {
          "offset": "0x00 - 0x03",
          "byteOffset": 0,
          "byteLength": 4,
          "lengthLabel": "4 B",
          "dataType": "char[4]",
          "fieldName": "magic",
          "description": "Fixed ASCII magic 'GGUF' (0x46554747 LE)"
        },
        {
          "offset": "0x04 - 0x07",
          "byteOffset": 4,
          "byteLength": 4,
          "lengthLabel": "4 B",
          "dataType": "uint32_le",
          "fieldName": "version",
          "description": "Format version (v2 or v3 in production)"
        },
        {
          "offset": "0x08 - 0x0F",
          "byteOffset": 8,
          "byteLength": 8,
          "lengthLabel": "8 B",
          "dataType": "uint64_le",
          "fieldName": "tensor_count",
          "description": "Number of tensor descriptors following KV section"
        },
        {
          "offset": "0x10 - 0x17",
          "byteOffset": 16,
          "byteLength": 8,
          "lengthLabel": "8 B",
          "dataType": "uint64_le",
          "fieldName": "metadata_kv_count",
          "description": "Number of typed metadata key-value entries"
        }
      ]
    },
    "securityProfile": {
      "riskLevel": "low",
      "allowsArbitraryCodeOrMacros": false,
      "xxeRisk": false,
      "polyglotPrependRisk": false,
      "pickleDeserializationRisk": false,
      "uploadValidationNotes": "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."
    },
    "codeSnippets": {
      "python": "import struct, sys\nwith open(sys.argv[1], \"rb\") as f:\n    magic, ver, n_tensors, n_kv = struct.unpack(\"<4sIQQ\", f.read(24))\n    assert magic == b\"GGUF\", f\"Invalid magic: {magic}\"\n    print(f\"GGUF v{ver}: {n_tensors} tensors, {n_kv} metadata KV pairs\")",
      "typescript": "export async function readGgufHeader(file: File) {\n  const dv = new DataView(await file.slice(0, 24).arrayBuffer());\n  return {\n    version: dv.getUint32(4, true),\n    tensorCount: dv.getBigUint64(8, true),\n    kvCount: dv.getBigUint64(16, true),\n  };\n}",
      "rust": "use std::{fs::File, io::Read};\nfn main() -> std::io::Result<()> {\n    let mut buf = [0u8; 24];\n    File::open(std::env::args().nth(1).expect(\"usage: <prog> <file>\"))?.read_exact(&mut buf)?;\n    let ver = u32::from_le_bytes(buf[4..8].try_into().expect(\"fixed-size byte window\"));\n    let tensors = u64::from_le_bytes(buf[8..16].try_into().expect(\"fixed-size byte window\"));\n    println!(\"GGUF v{ver}: {tensors} tensors\");\n    Ok(())\n}",
      "go": "package main\nimport (\"encoding/binary\"; \"fmt\"; \"io\"; \"os\")\nfunc main() {\n    f, err := os.Open(os.Args[1])\n    if err != nil {\n        fmt.Fprintln(os.Stderr, \"open:\", err)\n        os.Exit(1)\n    }\n    defer f.Close()\n    b := make([]byte, 24)\n    if _, err := io.ReadFull(f, b); err != nil {\n        fmt.Fprintln(os.Stderr, \"read:\", err)\n        os.Exit(1)\n    }\n    fmt.Printf(\"GGUF v%d tensors=%d\\n\", binary.LittleEndian.Uint32(b[4:8]), binary.LittleEndian.Uint64(b[8:16]))\n}"
    },
    "relatedFormats": [
      "safetensors",
      "onnx",
      "pt"
    ],
    "verifiedAt": "2026-11-14T16:09:03Z"
  },
  "samples": [
    {
      "id": "gguf-minimal",
      "filename": "minimal-llama.gguf",
      "variant": "minimal",
      "title": "Minimal GGUF v3 Llama Fixture",
      "description": "Compact GGUF v3 binary with Llama architecture KV metadata, 8-token vocabulary array, and 2 aligned tensors (F16 & Q8_0).",
      "localPath": "/fixtures/v1/gguf/minimal-llama.gguf",
      "cdnUrl": "https://fileformat.co/fixtures/v1/gguf/minimal-llama.gguf",
      "sizeBytes": 1120,
      "sha256": "2ec356e162053c781631412e0ef64fe4672618855458afc781eff05dbda10a5d",
      "expectValid": true
    },
    {
      "id": "gguf-realistic",
      "filename": "llama3-tiny.gguf",
      "variant": "realistic",
      "title": "Realistic Multi-Quantization Llama GGUF v3",
      "description": "Rich GGUF v3 model fixture with RoPE/GQA hyperparameters, multilingual/emoji tokenizer table, and F32/F16/Q8_0/Q4_K tensor descriptors.",
      "localPath": "/fixtures/v1/gguf/llama3-tiny.gguf",
      "cdnUrl": "https://fileformat.co/fixtures/v1/gguf/llama3-tiny.gguf",
      "sizeBytes": 6368,
      "sha256": "1e9c572f8666905c15ab3bd03689a613980af4547600b7eeccde39a387424044",
      "expectValid": true
    },
    {
      "id": "gguf-edge-case",
      "filename": "truncated-metadata.gguf",
      "variant": "edge-case",
      "title": "Truncated GGUF v3 Header (EOF Mid-KV)",
      "description": "Negative test fixture claiming 6 tensors and 14 KV entries but truncated at 112 bytes to verify parser bounds checking.",
      "localPath": "/fixtures/v1/gguf/truncated-metadata.gguf",
      "cdnUrl": "https://fileformat.co/fixtures/v1/gguf/truncated-metadata.gguf",
      "sizeBytes": 112,
      "sha256": "81fec5725175f7820eaebf9d3ddcc53edb19595f60f24e73a29ef13731e032c9",
      "expectValid": false,
      "edgeCaseTag": "Truncated EOF"
    }
  ]
}