safetensors/safetensors

safetensors – a safe, fast format for storing ML tensors

What it is – safetensors is a small open‑source library (Python bindings plus a Rust core) that defines a binary file format for serialising tensors (weights, activations, etc.) without using Python’s pickle. The format is deliberately simple: a tiny JSON header that describes each tensor and a contiguous byte buffer that holds the raw data. Because the header never contains executable code, files can be shared and loaded safely.

Why it matters – In deep‑learning workflows model weights are often shipped as large binary blobs. The default PyTorch format (.pt/pickle) can execute arbitrary code when loaded, which is a security risk for anyone downloading a model from the internet. safetensors removes that risk while still offering:

• Zero‑copy reads – the byte buffer can be memory‑mapped directly into a tensor, avoiding an extra copy on CPU.
• Lazy loading – you can inspect the header and load only the tensors you need, which is useful for distributed or multi‑GPU inference.
• No size limit – the format works for gigabyte‑scale models.
• Support for modern dtypes such as bfloat16 and fp8.

Key features (as described in the README)

Feature	How it works
Safety	Header is pure JSON; no code execution on load.
Zero‑copy	Tensor data is stored contiguously; libraries can map it directly (torch.UntypedStorage.from_file).
Lazy loading	Header lists each tensor’s byte offsets, so a consumer can read a single tensor without scanning the whole file.
Layout control	The creator decides the order of tensors in the file, enabling fast random access.
Unlimited file size	No 2 GiB cap like some protobuf‑based formats.
Bfloat16 / fp8 support	Native dtype codes are part of the spec.

Installation

# Python package (most common use)
pip install safetensors

If you want to build from source you need the Rust tool‑chain:

curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh   # install Rust
git clone https://github.com/huggingface/safetensors
cd safetensors/bindings/python
pip install setuptools_rust
pip install -e .

Quick‑start example (Python)

import torch
from safetensors import safe_open
from safetensors.torch import save_file

# Write two tensors to disk
weights = {
    "weight1": torch.zeros((1024, 1024)),
    "weight2": torch.zeros((1024, 1024)),
}
save_file(weights, "model.safetensors")

# Read them back lazily
tensors = {}
with safe_open("model.safetensors", framework="pt", device="cpu") as f:
    for key in f.keys():
        tensors[key] = f.get_tensor(key)

The safe_open context returns a lightweight handle that lets you query the header (f.keys()) and fetch only the tensors you need.

File format basics

• First 8 bytes – little‑endian unsigned integer N, the length of the JSON header.
• Next N bytes – UTF‑8 JSON object mapping tensor names to {dtype, shape, data_offsets}.
• Remaining bytes – raw tensor data concatenated back‑to‑back.
• An optional __metadata__ entry can store arbitrary string‑to‑string key/value pairs.
• No duplicate keys, no holes in the byte buffer, and everything is little‑endian row‑major.

Where it fits in the ML ecosystem

• Used by Hugging Face model hub to distribute large language‑model weights safely.
• Compatible with PyTorch, TensorFlow, NumPy, etc., via language‑specific bindings (the core is in Rust, but Python is the primary entry point).
• Serves as an alternative to formats like Pickle, HDF5, ONNX protobuf, MsgPack, or NumPy .npz when safety and fast random access are required.

License – Apache‑2.0 (permissive, commercial‑friendly).

---

All information above is taken directly from the repository’s README; no additional features have been inferred.