safetensors

On this page 8

safetensors is a file format and library for storing machine learning tensors that holds only raw numerical data and a small JSON header, so loading a file cannot execute arbitrary code. Among AI frameworks & tools, it has become the default format for sharing model weights on the Hugging Face Hub and in libraries such as Hugging Face Transformers and Diffusers.

The format was designed to replace pickle-based checkpoints, which can run any Python code when they are opened. It combines safety, speed and simplicity: a reader parses a bounded header, checks offsets and then maps the tensor bytes directly into memory, which also makes loading large language models noticeably faster.

How the safetensors file layout works

A safetensors file consists of three consecutive parts: a length prefix, a JSON header and a raw byte buffer. The design is deliberately minimal, which makes independent implementations in Rust, Python, C++ or JavaScript straightforward to write and to audit.

The header is a JSON object whose keys are tensor names. Each entry records the data type, the shape and a pair of data offsets that point into the byte buffer. An optional __metadata__ entry may hold free-form string pairs, such as the format version or the framework that produced the file.

PartSizeContent
Length prefix8 bytesUnsigned 64-bit little-endian integer giving the header size
JSON headerUp to 100 MBTensor names, dtype, shape, data_offsets, optional metadata
Byte bufferRest of the fileRaw tensor values, contiguous, little-endian, row-major
Structure of a safetensors file

The specification imposes strict validation rules. Offsets must not overlap, must cover the buffer without gaps, and the product of the shape and the element size must match the byte range exactly. A reader that enforces these checks rejects malformed or malicious files before it touches any tensor data.

Why safetensors is safer than pickle checkpoints

The central advantage of safetensors is that deserialization involves no code execution. Traditional PyTorch checkpoints (.bin, .pt, .pth) use Python pickle, a serialization protocol that can reconstruct arbitrary objects by calling functions during loading. A crafted pickle file can therefore run attacker-controlled commands the moment torch.load opens it.

Because a safetensors file contains only a header and numbers, the worst a hostile file can do is fail validation. The library was reviewed in an external security audit in 2023, commissioned jointly by Hugging Face, EleutherAI and Stability AI, which found no critical issues in the core parser. Mitigations such as the weights_only option in PyTorch reduce pickle risk, yet they narrow rather than remove the attack surface.

FormatCode execution on loadMain residual risk
Pickle checkpointPossible by designMalicious payload in a downloaded model
Pickle with weights_onlyRestricted to allowed typesBypasses through allowed classes or bugs
safetensorsNot possibleParser bugs, tampered but valid weights
GGUFNot possible in the formatParser bugs in the loading runtime
Security comparison of weight formats

A safe format does not make a model trustworthy. A file can still contain poisoned or backdoored weights, so provenance checks, checksums and trusted publishers remain necessary. safetensors removes one specific attack class, namely code execution during loading.

Performance: zero-copy loading and lazy access

safetensors loads quickly because the byte buffer already matches the in-memory layout of a tensor. The library can memory-map the file with mmap, which lets the operating system page data in on demand instead of copying the whole file through Python objects first. This is often described as zero-copy loading.

Lazy loading is the second benefit. Since the header lists every offset, a program can read only the tensors it needs, for example one layer for inspection or one shard for a particular GPU in tensor-parallel inference. Pickle checkpoints usually require unpickling the entire object graph before any single tensor is available.

Real speed gains depend on storage and hardware. On fast NVMe drives with a warm page cache, loading can be several times faster than with pickle, while on network file systems the bottleneck is usually bandwidth, not the format.

Supported data types and framework integration

safetensors supports the numeric data types used in modern training and inference, including reduced-precision formats. Each tensor carries a short dtype code in the header, and the library converts it to the matching type of the target framework.

Dtype codeElement sizeTypical use
F324 bytesFull-precision training and reference weights
F162 bytesInference on GPUs with half-precision support
BF162 bytesLarge language model training and release checkpoints
F8_E4M3 and F8_E5M21 byteFP8 inference and training on recent accelerators
I8 and U81 byteQuantized weights and auxiliary tensors
I64 and BOOL8 bytes and 1 byteIndex buffers, masks and position tables
Common dtype codes in safetensors headers

The core is written in Rust with Python bindings, and the Python package provides loaders for PyTorch, TensorFlow, Flax and JAX, NumPy, PaddlePaddle and MLX. Hugging Face Transformers saves models in safetensors by default through save_pretrained, and large models are split into sharded files described by an index file named model.safetensors.index.json.

How safetensors compares with other model formats

safetensors stores weights only, not the computation graph or the code that uses them. Other formats in the ecosystem make different trade-offs between portability, quantization and execution.

FormatContainsTypical consumer
safetensorsNamed tensors and string metadataPyTorch, Transformers, Diffusers, ComfyUI
PyTorch pickleArbitrary Python objects including tensorsLegacy PyTorch training scripts
GGUFQuantized tensors, tokenizer and model metadatallama.cpp, Ollama, LM Studio
ONNXComputation graph plus weightsONNX Runtime, TensorRT, edge deployment
TensorFlow SavedModelGraph, variables and signaturesTensorFlow Serving and LiteRT conversion
safetensors compared with related formats

In practice, safetensors is the interchange format for original weights, while GGUF or ONNX files are often derived artifacts produced by conversion tools for a specific runtime.

Limitations and common mistakes

The format is intentionally narrow, and several limitations follow from that choice. Teams that understand them avoid confusing load errors and silent mismatches.

  • No shared or aliased tensors: tied weights, such as input and output embeddings, must be deduplicated before saving, which save_model handles automatically.
  • No optimizer state objects or code: training state, schedulers and custom classes need separate files or a separate checkpoint mechanism.
  • Metadata values are strings only: structured configuration belongs in a companion config.json, not in the header.
  • Converting an untrusted pickle is not safe: the conversion itself unpickles the file, so it must run in an isolated environment.
  • Valid file, wrong model: matching tensor names and shapes do not guarantee that the weights belong to the expected architecture or version.

The simple explanation

A trained AI model is mostly a huge collection of numbers. Those numbers must be saved to a file so that other people and programs can use them. Older formats saved them in a way that could also hide instructions, and opening such a file could run those instructions on your computer.

safetensors is like a sealed box with a clear packing list. The list on top says what each item is, how big it is and where it sits in the box. The box contains only numbers, so opening it cannot start any hidden program, and you can take out just the item you need without unpacking everything.

How it is used in practice

A machine learning team at a mid-sized software company wants to test an open-weight language model with about 8 billion parameters for internal document search. The model is published on a public hub in two forms: older pickle files and a set of four BF16 safetensors shards totaling roughly 16 GB.

The security policy of the team forbids loading pickle files from external sources on production machines, so the engineers download only the safetensors shards and the index file. Their inference server memory-maps the shards and loads each layer directly onto two GPUs, reading only the tensors that belong to each device.

The result is a model that starts in well under a minute from local NVMe storage, without any code from the download being executed. The team also records the SHA-256 checksum of each shard, because the safe format protects against code execution but not against tampered weights.