Safetensors

Safetensors is a secure, fast file format for storing neural network weights developed by Hugging Face to replace Python's unsafe pickle-based formats — eliminating the arbitrary code execution vulnerability inherent in `.pth` and `.bin` files by using a pure data format (like JSON for tensors) that cannot contain executable code, while also providing instant loading via memory mapping that makes opening a 100 GB model file as fast as opening a 1 MB file.

What Is Safetensors?

• Definition: A binary file format (`.safetensors` extension) that stores tensors (multi-dimensional arrays of numbers) as raw data with a JSON header describing tensor names, shapes, and data types — designed to be safe to load from untrusted sources because the format physically cannot contain executable code.
• The Security Problem: Python's `pickle` module (used by PyTorch's `.pth` and `.bin` formats) can execute arbitrary code during deserialization — loading a malicious model file from the internet can install malware, exfiltrate data, or compromise your system. This is a real, exploited vulnerability.
• The Safety Guarantee: Safetensors is a pure data format — the loader reads a JSON header (tensor metadata) and memory-maps raw byte buffers (tensor data). There is no code execution path, no deserialization of Python objects, no eval() calls. Loading a safetensors file is as safe as reading a JPEG.
• Memory Mapping: Safetensors uses `mmap` to map the file directly into virtual memory — the OS loads pages on demand as they're accessed, meaning a 100 GB model file "loads" in milliseconds (the actual data is read lazily from disk as needed).

Why Safetensors Matters

• Security: Eliminates the #1 supply chain attack vector for ML models — malicious pickle files on Hugging Face Hub, GitHub, or model sharing sites can no longer compromise systems that use safetensors exclusively.
• Speed: Memory-mapped loading is 2-100× faster than pickle deserialization — a 7B parameter model loads in ~1 second with safetensors vs 10-30 seconds with pickle, because mmap avoids copying data into Python objects.
• Lazy Loading: Only the tensors you access are read from disk — if you need only the embedding layer of a 70B model, only those bytes are loaded. Pickle must deserialize the entire file.
• Framework Agnostic: Safetensors files can be loaded in PyTorch, TensorFlow, JAX, NumPy, and Rust — the format is framework-independent, unlike pickle which is Python-specific.
• Hugging Face Default: Safetensors is now the default format on the Hugging Face Hub — new model uploads use safetensors, and existing models are being converted. `from_pretrained()` automatically prefers safetensors files when available.

Safetensors vs Pickle Formats

Safetensors is the secure, fast model weight format that eliminated the pickle vulnerability from the ML ecosystem — by replacing executable pickle serialization with a pure data format that uses memory mapping for instant loading, Safetensors made it safe to download and load model weights from the internet while simultaneously making model loading 2-100× faster.