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.
| Part | Size | Content |
|---|---|---|
| Length prefix | 8 bytes | Unsigned 64-bit little-endian integer giving the header size |
| JSON header | Up to 100 MB | Tensor names, dtype, shape, data_offsets, optional metadata |
| Byte buffer | Rest of the file | Raw tensor values, contiguous, little-endian, row-major |
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.
| Format | Code execution on load | Main residual risk |
|---|---|---|
| Pickle checkpoint | Possible by design | Malicious payload in a downloaded model |
| Pickle with weights_only | Restricted to allowed types | Bypasses through allowed classes or bugs |
| safetensors | Not possible | Parser bugs, tampered but valid weights |
| GGUF | Not possible in the format | Parser bugs in the loading runtime |
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 code | Element size | Typical use |
|---|---|---|
| F32 | 4 bytes | Full-precision training and reference weights |
| F16 | 2 bytes | Inference on GPUs with half-precision support |
| BF16 | 2 bytes | Large language model training and release checkpoints |
| F8_E4M3 and F8_E5M2 | 1 byte | FP8 inference and training on recent accelerators |
| I8 and U8 | 1 byte | Quantized weights and auxiliary tensors |
| I64 and BOOL | 8 bytes and 1 byte | Index buffers, masks and position tables |
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.
| Format | Contains | Typical consumer |
|---|---|---|
| safetensors | Named tensors and string metadata | PyTorch, Transformers, Diffusers, ComfyUI |
| PyTorch pickle | Arbitrary Python objects including tensors | Legacy PyTorch training scripts |
| GGUF | Quantized tensors, tokenizer and model metadata | llama.cpp, Ollama, LM Studio |
| ONNX | Computation graph plus weights | ONNX Runtime, TensorRT, edge deployment |
| TensorFlow SavedModel | Graph, variables and signatures | TensorFlow Serving and LiteRT conversion |
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_modelhandles 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.