Find a model's real context window in the GGUF header (no llama.cpp)

Steps#

1. Save the script as ggufctx.py.

   #!/usr/bin/env python3
   """Print a GGUF file's trained context length and RoPE scaling keys.
   
   Reads only the metadata header (no tensor data), stdlib only, never writes.
   Usage: python3 -I ggufctx.py <FILE.gguf>
   """
   import struct
   import sys
   
   # GGUF metadata value types (ggml docs/gguf.md, enum gguf_metadata_value_type)
   FIXED = {0: "<B", 1: "<b", 2: "<H", 3: "<h", 4: "<I", 5: "<i", 6: "<f",
            7: "<?", 10: "<Q", 11: "<q", 12: "<d"}
   STRING, ARRAY = 8, 9
   
   
   def wanted(key):
       return (key in ("general.architecture", "general.name")
               or key.endswith(".context_length")
               or ".rope.scaling." in key
               or key.startswith("split."))
   
   
   def main(path):
       with open(path, "rb") as f:
           def read(n):
               b = f.read(n)
               if len(b) != n:
                   sys.exit(f"{path}: header ends early (truncated file?)")
               return b
   
           def num(fmt):
               return struct.unpack(fmt, read(struct.calcsize(fmt)))[0]
   
           def string():
               return read(num("<Q")).decode("utf-8", "replace")
   
           def value(t):
               if t == STRING:
                   return string()
               if t == ARRAY:
                   et, n = num("<I"), num("<Q")
                   if et in FIXED:
                       read(n * struct.calcsize(FIXED[et]))  # skip, works on pipes too
                   else:
                       for _ in range(n):
                           value(et)
                   return f"<array, {n} items>"
               if t not in FIXED:
                   sys.exit(f"{path}: unknown value type {t}")
               return num(FIXED[t])
   
           if read(4) != b"GGUF":
               sys.exit(f"{path}: not a GGUF file (first 4 bytes are not 'GGUF')")
           version, n_tensors, n_kv = num("<I"), num("<Q"), num("<Q")
           print(f"gguf version {version}, {n_tensors} tensors, {n_kv} metadata keys")
           for _ in range(n_kv):
               key = string()
               v = value(num("<I"))
               if wanted(key):
                   print(key, v)
   
   
   if __name__ == "__main__":
       if len(sys.argv) != 2:
           sys.exit("usage: python3 -I ggufctx.py <FILE.gguf>")
       main(sys.argv[1])
   

   Check that it parses:

   $ python3 -I ggufctx.py
   usage: python3 -I ggufctx.py <FILE.gguf>
   

   Expected: the usage line (exit code 1). A SyntaxError means the paste lost indentation.

2. Run it on the model file. On the machine that has the file:

   python3 -I ggufctx.py <FILE.gguf>
   

   $ python3 -I ggufctx.py ~/models/llama-2-7b.Q4_0.gguf
   gguf version 2, 291 tensors, 19 metadata keys
   general.architecture llama
   general.name LLaMA v2
   llama.context_length 4096
   

   If the file is on another box, pipe the script over SSH instead of copying it there (- makes Python read the script from stdin; the file path is the remote one):

   ssh <HOST> 'python3 -I - <FILE.gguf>' < ggufctx.py
   

   $ ssh a9 'python3 -I - ~/models/Laguna-XS-2.1-GGUF/Laguna-XS-2.1-Q8_0.gguf' < ggufctx.py
   gguf version 3, 678 tensors, 61 metadata keys
   general.architecture laguna
   general.name Laguna XS 2.1
   laguna.context_length 262144
   laguna.rope.scaling.type yarn
   laguna.rope.scaling.factor 32.0
   laguna.rope.scaling.original_context_length 8192
   laguna.rope.scaling.yarn_attn_factor 1.3465735912322998
   laguna.rope.scaling.yarn_beta_fast 64.0
   laguna.rope.scaling.yarn_beta_slow 1.0
   

   Expected: a gguf version line, then general.architecture and one <arch>.context_length line. On the 35.6 GB Laguna file the run took 0.070 s wall time, because only the header is read. Errors: see Failure modes, rows 1-4.

3. For a split model, run it on shard 1. Only the first shard carries the model metadata:

   $ ssh a9 'python3 -I - ~/models/Laguna-S-2.1-GGUF/Laguna-S-2.1-UD-Q5_K_XL-00001-of-00003.gguf' < ggufctx.py
   gguf version 3, 0 tensors, 72 metadata keys
   general.architecture laguna
   general.name Laguna-S-2.1
   laguna.context_length 262144
   laguna.rope.scaling.type yarn
   laguna.rope.scaling.factor 32.0
   laguna.rope.scaling.original_context_length 8192
   laguna.rope.scaling.yarn_attn_factor 1.0
   laguna.rope.scaling.yarn_beta_fast 32.0
   laguna.rope.scaling.yarn_beta_slow 1.0
   split.no 0
   split.tensors.count 814
   split.count 3
   

   Expected: split.no 0 (numbering starts at 0) and the context_length line. In this file shard 1 holds no tensors at all, only metadata. If you see only split.* lines, you ran a later shard: see Failure modes, row 5.

4. Read the numbers.

   • <arch>.context_length is the model's context window. The GGUF spec defines it as the "length of the context (in tokens) that the model was trained on". In both files cross-checked here (Laguna-XS, Qwen3-30B-A3B) it equals max_position_embeddings in the original model's config.json. That is usually the ceiling to serve at, but a model card can state a smaller native window (Qwen3 example below), so read the card too (Verify).
   • <arch>.rope.scaling.type yarn with factor and original_context_length means the window was reached by YaRN-extending a shorter base: Laguna-XS is 32.0 × 8192 = 262144. In all seven YaRN files on this box (factors 16 to 128: DeepSeek-V4-Flash, Mistral-Small-4, three gpt-oss, two Laguna), factor × original_context_length equals context_length; gpt-oss-120b is 32.0 × 4096 = 131072:

     $ ssh a9 'python3 -I - ~/models/gpt-oss-120b-MXFP4.gguf' < ggufctx.py
     gguf version 3, 687 tensors, 36 metadata keys
     general.architecture gpt-oss
     general.name gpt-oss-120b
     gpt-oss.context_length 131072
     gpt-oss.rope.scaling.type yarn
     gpt-oss.rope.scaling.factor 32.0
     gpt-oss.rope.scaling.original_context_length 4096
     gpt-oss.rope.scaling.yarn_beta_fast 32.0
     gpt-oss.rope.scaling.yarn_beta_slow 1.0
     

   • No rope.scaling lines: the file stores no scaling. context_length is then whatever the config declares, which is not always the native window the card names:

     $ ssh a9 'python3 -I - ~/models/Qwen3-30B-A3B-Q4_K_M.gguf' < ggufctx.py
     gguf version 3, 579 tensors, 37 metadata keys
     general.architecture qwen3moe
     general.name Qwen3 30B A3B
     qwen3moe.context_length 40960
     

     The Qwen3-30B-A3B card says "32,768 natively" and explains that max_position_embeddings = 40,960 reserves 32,768 tokens for output plus 8,192 for prompts; its config.json has max_position_embeddings 40960 and rope_scaling null.
   • The yarn_* keys are inputs your inference engine has to read. A build that ignores them runs the model with its own defaults (see Notes, llama.cpp #30331).

5. Compare with the context your server actually uses. The configured value is not proof; read the number the server prints at load. With llama-server (-c / --ctx-size; 0 means "loaded from model"), it is the n_ctx_slot line in the server log:

   $ ssh a9 'grep -H n_ctx_slot ~/bench-archive/serve/laguna-xs-q8-vulkan-new-2026101*.log'
   /home/user/bench-archive/serve/laguna-xs-q8-vulkan-new-20261016T050201.log:0.09.628.876 I srv    load_model: initializing, n_slots = 1, n_ctx_slot = 131072, kv_unified = 'false'
   /home/user/bench-archive/serve/laguna-xs-q8-vulkan-new-20261016T143358.log:0.10.328.547 I srv    load_model: initializing, n_slots = 1, n_ctx_slot = 262144, kv_unified = 'false'
   

   For your own server: grep n_ctx_slot <SERVER_LOG>. Expected: the served value equals context_length from step 2. The first log above is a server started at 131072 for a model whose header says 262144: half the trained window. The second is the same model restarted at 262144. A lower served value is legitimate only when you chose it (memory budget); otherwise raise -c (or your engine's equivalent) to context_length.