Here are complete study notes for understanding safetensors models — designed for clarity, beginner-friendly learning, and covering all basic doubts. Useful for Hugging Face, PyTorch, Transformers, LLMs, and more.
📦 What is safetensors?
safetensors is a safe, fast, and portable file format used to store machine learning model weights (usually as an alternative to .bin or .pt files in PyTorch).
🔐 Why "safe"?
Because it:
Does not allow arbitrary code execution
Prevents security vulnerabilities during model loading (vs. pickle-based formats)
📁 Safetensors vs PyTorch .bin
Feature .bin / .pt (PyTorch) safetensors
📁 Safetensors vs PyTorch .bin
| Feature | .bin / .pt (PyTorch) |
safetensors |
|---|---|---|
| ✅ Security | ❌ Untrusted pickle code | ✅ Fully secure format |
| 🧠 Speed | Moderate load speed | 🚀 Extremely fast loading |
| 🧱 Format | PyTorch specific pickle | Cross-framework tensor map |
| 📦 Portability | Low (Python only) | High (language agnostic) |
| 🔍 Inspectable? | ❌ No | ✅ Yes (via CLI or code) |
🔧 When is safetensors used?
Transformers models on Hugging Face: e.g., LLaMA, Mistral, BERT
Custom PyTorch/TensorFlow model weights
High-speed inference applications
Secure model sharing in research and production
📚 File Structure of a Safetensors Model
A .safetensors file stores:
A JSON header (with tensor names, shapes, dtypes, offsets)
A flat binary blob of all tensor data
{
"model.weights.0": {"dtype": "float32", "shape": [1024, 1024], "offsets": [0, 4194304]},
}
🔄 How to Save and Load Safetensors
🐍 Python Code Example (PyTorch):
from safetensors.torch import save_file, load_file
import torch
# Example tensor dict
tensors = {
"layer1.weight": torch.randn(2, 2),
"layer1.bias": torch.randn(2)
}
# Save
save_file(tensors, "model.safetensors")
# Load
loaded = load_file("model.safetensors")
print(loaded["layer1.weight"])
🤖 Load Safetensors in Hugging Face Transformers
✅ Transformers automatically detect .safetensors
from transformers import AutoModelForCausalLM, AutoTokenizer
model = AutoModelForCausalLM.from_pretrained(
"TheBloke/Llama-2-7B-GGUF",
trust_remote_code=True # required for some models
)
tokenizer = AutoTokenizer.from_pretrained("TheBloke/Llama-2-7B-GGUF")
If the repo has model.safetensors, it will use it.
| Feature | Description |
|---|---|
📁 .safetensors |
Secure format for storing weights |
| 🧠 Frameworks | PyTorch, TensorFlow, Rust, etc. |
| 🔐 Security | No arbitrary code execution (unlike pickle) |
| ⚡ Speed | Loads faster than .bin |
| 🔍 Inspectable | Easily check weights and shapes |
| 🤝 Interoperable | Can be used across languages and systems |
🛠️ CLI Tool
Install:
pip install safetensors
Inspect:
safetensors-cli inspect model.safetensors
Convert from PyTorch:
safetensors-cli convert model.bin model.safetensors
⚠️ Common Beginner Doubts
❓Is .safetensors just a renamed .pt or .bin? No. It’s a completely different format — structured binary + JSON header. It’s not pickled Python objects.
❓Can I use it without PyTorch? Yes. It has libraries in Rust, Python, and more. Tensor data is pure and framework-agnostic.
❓What if my model is only in .bin? You can convert it with Hugging Face CLI tools or manually (load weights and save as .safetensors).
❓Is it only for Transformers? No. You can use it for any ML model, not just Transformers.
❓Can I load .safetensors into TensorFlow? Yes — there are TensorFlow bindings. However, most community usage is in PyTorch.
❓How big are .safetensors files? Roughly same size as .bin but load faster due to optimized memory access.
🧠 Use Cases
LLMs (LLaMA, Mistral, Falcon) with Hugging Face
Secure sharing of models (e.g., in open source or competitions)
Deployments where performance and security matter
📌 Quick Recap
✅ .safetensors = secure, fast, inspectable, portable model format ✅ Prevents code execution risks from .bin/.pt ✅ Hugging Face models fully support it ✅ Can be used with or without PyTorch ✅ Ideal for LLMs and secure environments
💬 Want to Try More?
Let me know if you want:
⚙️ A tool to convert .bin → .safetensors
🌐 Serve models with FastAPI + safetensors
🧠 Use it with Hugging Face transformers LLMs
📂 Inspect tensor names, shapes, dtypes programmatically
I'll build that example for you.