Safetensors

0.7.0 · active · verified Sat Mar 28

Safetensors is a Python library and file format for securely and efficiently storing and distributing deep learning tensors. It provides a safer, zero-copy alternative to pickle-based serialization, emphasizing speed, security, and ease of use. The library is actively maintained by Hugging Face, with its latest version being 0.7.0, and has a frequent release cadence, often aligning with new tensor datatype support or framework integrations.

Warnings

breaking When using new sub-byte dtypes like FP4/FP6, operations that lead to unused or unaligned bits within a byte will raise a `MisalignedByte` exception. This ensures data integrity but requires careful handling for these advanced types.
Fix: Ensure tensors are properly aligned or handle `MisalignedByte` exceptions. Be aware of how FP4/FP6 types are represented and accessed.
gotcha The JSON header parsing, which delegates to `serde` (in Rust), explicitly rejects duplicate keys. Other JSON parsers (e.g., Python's built-in `json` module) might silently keep the first or last duplicate, leading to parser differentials if not using the `safetensors` library's own loading mechanism.
Fix: Always use the `safetensors` library's provided `safe_open` or `load_file` functions to ensure consistent and secure JSON header parsing. Avoid external JSON parsers for `.safetensors` headers.
gotcha For PyTorch users, `torch`'s `float4_e2m1fn_x2` dtype actually represents two FP4 values. `safetensors` silently casts a tensor of shape `[..., z]` into `[..., z/2]` for this type, using the last dimension to 'swallow' the x2 contained within the types. This behavior might be unexpected and is subject to change.
Fix: Be mindful of potential shape changes when working with PyTorch's `float4_e2m1fn_x2` and `safetensors`. Explicitly check tensor shapes after loading.
deprecated The `safe_load_file` function (or equivalent `load_file` in framework-specific APIs) no longer defines a default framework. Users must explicitly set the `framework` parameter (e.g., `framework='torch'`).
Fix: Update calls to `load_file` or `safe_open` to include the `framework` argument, e.g., `with safe_open('model.safetensors', framework='pt', device='cpu') as f:`.

Install

pip install safetensors Install Safetensors

Imports

safe_open
```
from safetensors import safe_open
```
Main entry point for loading safetensors files generically.
save_file
```
from safetensors.torch import save_file
```
Framework-specific save function for PyTorch tensors. Similar imports exist for other frameworks (e.g., `.numpy`, `.tensorflow`).
load_file
```
from safetensors.torch import load_file
```
Framework-specific load function for PyTorch tensors. Similar imports exist for other frameworks.

Quickstart

This quickstart demonstrates how to save and load PyTorch tensors using the `safetensors.torch` API. It creates a dictionary of dummy tensors, saves them to a `.safetensors` file, then loads them back, and finally cleans up the file.

import torch
from safetensors.torch import save_file, load_file
import os

# Define some dummy tensors
tensors = {
    "weight1": torch.zeros((1024, 1024)),
    "bias": torch.ones((1024,)),
    "embedding": torch.randn((500, 768))
}

file_path = "my_model.safetensors"

# Save the tensors to a safetensors file
save_file(tensors, file_path)
print(f"Tensors saved to {file_path}")

# Load the tensors from the safetensors file
loaded_tensors = load_file(file_path)
print("Tensors loaded:")
for key, value in loaded_tensors.items():
    print(f"  {key}: shape={value.shape}, dtype={value.dtype}")

# Clean up the created file
os.remove(file_path)
print(f"Cleaned up {file_path}")

view raw JSON →