This page follows
docs/gguf.md
in the ggml repository, read 2026-11-12, version 3 of the format. Numbers are little-endian unless the file was written big-endian (version 3
allows that; nothing in the file says so, and readers assume little-endian).
Header
| Offset | Type | Field |
|---|---|---|
0 | uint32 | magic: the bytes GGUF. |
4 | uint32 | version: 3. |
8 | uint64 | tensor_count. |
16 | uint64 | metadata_kv_count. |
24 | … | The metadata key-value pairs, then the tensor infos, padding, and the tensor data. |
Version 1 used 32-bit counts and string lengths; version 2 changed most of them to 64-bit; version 3 added big-endian files.
Metadata
Each pair is a key (a string), a value type (uint32), and the value. A string is a
uint64 length and UTF-8 bytes, with no NUL. Keys are lower-case
snake_case parts separated by dots, at most 65,535 bytes.
| Type | Name | Type | Name |
|---|---|---|---|
| 0 | UINT8 | 7 | BOOL (1 byte, 0 or 1) |
| 1 | INT8 | 8 | STRING |
| 2 | UINT16 | 9 | ARRAY: element type (uint32), count (uint64), elements |
| 3 | INT16 | 10 | UINT64 |
| 4 | UINT32 | 11 | INT64 |
| 5 | INT32 | 12 | FLOAT64 |
| 6 | FLOAT32 |
Standard keys
| Key | Meaning |
|---|---|
general.architecture | Required: the model family, such as llama; it prefixes the architecture keys. |
general.quantization_version | Required when any tensor is quantised. |
general.alignment | Alignment of tensor data, a multiple of 8; 32 if absent. |
general.name, author, version, organization, basename, finetune, description, quantized_by, size_label | Descriptions. |
general.license, license.name, license.link | Licence. |
general.url, doi, uuid, repo_url | Where the model comes from. |
general.tags, languages, datasets | String arrays. |
general.file_type | The main quantisation of the file. |
general.source.*, general.base_model.count, general.base_model.N.* | The model it was converted or derived from. |
[arch].context_length, embedding_length, block_count, feed_forward_length, attention.head_count, attention.head_count_kv, rope.*… | Architecture hyperparameters, under the architecture’s name. |
tokenizer.ggml.model | llama, replit, gpt2, rwkv… |
tokenizer.ggml.tokens, scores, token_type, merges, added_tokens | The vocabulary. |
tokenizer.ggml.bos_token_id, eos_token_id, unknown_token_id, separator_token_id, padding_token_id | Special tokens. |
tokenizer.huggingface.json, tokenizer.rwkv.world, tokenizer.chat_template | Other tokenizer data; the chat template is Jinja. |
File names
The convention is
[Sidecar]BaseName-SizeLabel-FineTune-Version-Encoding-Type-Shard.gguf,
such as Mixtral-8x7B-v0.1-KQ2.gguf (the document’s example): an optional sidecar prefix
(mmproj, mtp), size label such as 8x7B,
version v1.0, encoding (the quantisation), type LoRA or
vocab, and shard 00001-of-00003.