Tensor files
How a tensor is stored
A tensor is one named array of numbers. A dtype says how each number is packed into bytes. A container is the file around one or more tensors.
- 1
One tensor
A name, a dtype, a shape, and the bytes. The shape is listed outermost first.
What a tensor contains - 2
The dtype
float32, bfloat16, int8, and the block types used by quantized weights. Each file has its own names.
Names across formats - 3
The file
safetensors, GGUF, npy, and the other files that carry those tensors.
Containers
A file or directory that holds tensors, with names and metadata around them.
.safetensors
safetensors
Hugging Face's safe, mmap-friendly tensor container. An 8-byte little-endian header length N, an N-byte UTF-8 JSON header mapping tensor names to {dtype, shape, data_offsets}, plus an optional "__metadata__" string->string map, then one contiguous byte buffer. Tensors are dense, little-endian, C-order, with no strides. Loading cannot execute code. It is the default format for HF Transformers / Diffusers checkpoints; large models are sharded with a JSON index file.
.gguf
GGUF
Single-file, mmap-friendly container used by ggml / llama.cpp / whisper.cpp and derivatives. Fixed header, typed key/value metadata section, tensor-info table, zero-padding to an alignment boundary, then a tensor data blob. Tensors may use plain element types (F32/F16/BF16/I8..I64/F64) or ggml block-quantized types (Q4_0, Q8_0, K-quants, IQ-quants, TQ, MXFP4, NVFP4, Q1_0, Q2_0). Dimension order is ggml order: ne[0] is the innermost (fastest-varying, contiguous) dimension, i.e. the REVERSE of numpy/PyTorch shape order.
.pt
PyTorch torch.save checkpoint
torch.save writes an uncompressed ZIP (PyTorch's own writer, "inline_container") with one top-level folder holding a pickle of the user's object (data.pkl) and one record per storage (data/<key>), each 64-byte aligned in the file. Tensors in the pickle are reduce-calls to torch._utils._rebuild_tensor_v2/v3 whose storage argument is a persistent id resolved to a data/ record. Because the container is pickle, loading can run arbitrary code unless restricted to an allowlist (weights_only=True, default since torch 2.6). HF "pytorch_model.bin" is this format; sharding uses pytorch_model.bin.index.json (same schema as the safetensors index).
executes code on loadSingle tensors
A file whose job is one array, or a plain-text copy of one.