Skip to main content
Zubnet AI › Learn › Wiki › Safetensors
Infrastructure

Safetensors

Also known as: .safetensors
A simple, secure file format for storing model weights that can't run hidden code and loads very quickly.

Why it matters

Safetensors is now the standard format for sharing model weights. It's the default in Hugging Face's Transformers and Diffusers libraries, and it's what most model creators publish. For anyone downloading models from the internet, it removes a real security risk: researchers have found malicious pickle-based models uploaded to public hubs.

It's also fast. Safetensors files can be memory-mapped, meaning the operating system loads only the parts you need, when you need them, without extra copies. Large models load noticeably faster, and you can read just a few tensors from a huge file without loading the rest.

Deep Dive

When you download an open model from Hugging Face, the weights usually come as one or more .safetensors files. The format was created by Hugging Face in 2022 to replace PyTorch's older default, which saved weights using Python's pickle format in .bin or .pt files.

The problem with pickle is that loading a pickle file can execute arbitrary code. A malicious model file could install malware the moment you load it. Safetensors stores only data, raw numbers plus a small description of their shapes, so loading it can never run code.

What's Inside the File

The format is deliberately simple:

  1. An 8-byte number saying how long the header is.
  2. A JSON header listing every tensor: its name, data type (such as F16, BF16 or F32), shape and where its bytes sit in the file. It can also hold free-form metadata.
  3. The raw tensor data, one block after another.

That's it. Because there's no code and no complex structure, the format is easy to implement in any language, and an independent security audit commissioned in 2023 found no critical issues.

Sharded Models

Big models are split into several files, such as model-00001-of-00004.safetensors, plus an index file (model.safetensors.index.json) that maps each tensor name to the file it lives in. Tools read the index and load the pieces automatically.

Safetensors Versus Other Formats

  • Pickle (.bin, .pt, .ckpt): flexible but unsafe to load from untrusted sources. Only use it for files you trust, and prefer loading options that restrict what can run.
  • GGUF: the single-file format used by llama.cpp, Ollama and LM Studio. It packs weights, tokenizer and settings together and is designed for quantized local inference. Many GGUF files are converted from safetensors originals.
  • ONNX: stores both the weights and the computation graph, so a model can run on different runtimes and hardware without its original code.

Practical Notes

Safetensors holds weights, not the whole model recipe. You still need the config file (config.json), tokenizer files and the code that defines the architecture. When a repository offers both .bin and .safetensors versions, choose safetensors. Fine-tuned LoRA adapters are usually shipped as small safetensors files too (adapter_model.safetensors).

← All Terms
ESC