Safetensors: Why It's the Default

~22 min · ops, safetensors, security

Level 0Scout

0 XP0/50 lessons0/10 achievements

0/120 XP to next level120 XP to go0% complete

Pickle is a security hole

The legacy .bin format for HF models is a Python pickle. Loading a pickle file is equivalent to running the producer's Python code. A malicious pickle can do anything a Python process can: open sockets, exfiltrate environment variables, modify ~/.ssh, install crypto miners. This is not theoretical. The Hub has caught actively malicious models in the wild.

Safetensors fixes that

Safetensors is a flat tensor container: a JSON header with metadata + offsets, a binary blob with raw tensor bytes. No code, no opcodes, no execution surface. Loading is memory-mapping. Faster too — fewer Python allocations, zero-copy paths in many cases.

The migration

Since transformers 4.34 (late 2023), save_pretrained writes safetensors by default. Most popular models on the Hub now ship both .bin and .safetensors. When loading, pass ignore_patterns=["*.bin"] to snapshot_download if you want to be sure the safe version is what you actually have on disk.

Code

Inspect a safetensors file without loading it·python

from safetensors import safe_open

with safe_open("model.safetensors", framework="pt") as f:
    print("metadata:", f.metadata())
    for name in f.keys():
        tensor = f.get_tensor(name)
        print(name, tuple(tensor.shape), tensor.dtype)
        break

Force safetensors-only download·python

from huggingface_hub import snapshot_download

path = snapshot_download(
    repo_id="meta-llama/Llama-3.1-8B-Instruct",
    allow_patterns=["*.safetensors", "*.json", "tokenizer*"],
    ignore_patterns=["*.bin", "*.h5", "*.ot"],
)

External links

Exercise

Pick three popular models. For each, use the Hub web UI to find the file list and verify both .bin and .safetensors are shipped. Use snapshot_download with ignore_patterns=['*.bin'] to download only safetensors. Verify the model loads correctly.

Progress

Progress is local-only — sign in to sync across devices.

← 🖼️ Spaces and AppsQuiz · 5 questions Next →Quantization Formats Cheat Sheet

Spotted a bug or have feedback on this page?Report an Issue

Comments 0

🔔 Reply notifications (sign in)

No comments yet — be the first.