safetensors

How to read it

[N: u64 LE][header: N bytes UTF-8 JSON, space padded][byte buffer]. File size = 8 + N + buffer length.

N

u64le. header length in bytes

header

utf8[N]. JSON Header object, optionally followed by 0x20 padding

buffer

bytes[*]. tensor bytes back to back, in data_offsets order, without gaps

0        8                    8+N                                    EOF
+--------+--------------------+--------------------------------------+
| N u64  | {"__metadata__":..,| t0 bytes | t1 bytes | ... | tk bytes |
|   LE   |  "t0":{...},...}   |                                      |
|        |  + ' ' padding     |  offsets are relative to byte 8+N    |
+--------+--------------------+--------------------------------------+

One tensor

name

header key

dtype

TensorInfo.dtype -> dtypes[].canonical

shape

TensorInfo.shape (already row-major, outermost first)

data_offset

8 + N + data_offsets[0] (absolute in file)

nbytes

data_offsets[1] - data_offsets[0]

order

always C

strides

implicit C-contiguous

Example

The specs test vector. The header is one JSON object. The header below is spaced for reading; the file pads that JSON with spaces out to a multiple of 8.

small.safetensors1,464 bytes

{
  "__metadata__": {
    "source": "tensor-format-specs test vector"
  },
  "s_f32": {
    "dtype": "F32",
    "shape": [],
    "data_offsets": [
      0,
      4
    ]
  },
  "w_f32": {
    "dtype": "F32",
    "shape": [
      4,
      64
    ],
    "data_offsets": [
      4,
      1028
    ]
  },
  "i_i32": {
    "dtype": "I32",
    "shape": [
      3,
      2
    ],
    "data_offsets": [
      1028,
      1052
    ]
  },
  "e_bf16": {
    "dtype": "BF16",
    "shape": [
      2,
      3
    ],
    "data_offsets": [
      1052,
      1064
    ]
  },
  "b_f16": {
    "dtype": "F16",
    "shape": [
      8
    ],
    "data_offsets": [
      1064,
      1080
    ]
  }
}