Safetensors

0.7.0 verified Tue May 12 auth: no python install: verified quickstart: stale

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.

pip install safetensors

Common errors

error ModuleNotFoundError: No module named 'safetensors' ↓

cause The 'safetensors' library is not installed in the current Python environment.

fix

pip install safetensors

error safetensors_rust.SafetensorsError: Error while deserializing header: InvalidHeader ↓

cause The file being loaded is either corrupted, not a valid .safetensors file, or has an incorrect header (e.g., a pickle file renamed to .safetensors).

fix

Verify the file's integrity and ensure it was genuinely created and saved in the safetensors format. Do not rename non-safetensors files to .safetensors.

error TypeError: safetensors.save_file() missing 1 required positional argument: 'filename' ↓

cause The `safetensors.save_file` function requires both the dictionary of tensors and the output filename as arguments, but the filename was omitted.

fix

safetensors.save_file(tensors_dict, 'path/to/your/file.safetensors')

error ValueError: expected `tensor` to be dict-like, got type `<class 'str'>` ↓

cause The `safetensors.save_file` function expects the first argument to be a dictionary mapping string keys to tensor-like objects, but received a non-dictionary type.

fix

Ensure the data passed to save_file is a dictionary, where keys are strings and values are actual tensors (e.g., NumPy arrays, PyTorch tensors, TensorFlow tensors). import numpy as np import safetensors data_to_save = {"my_tensor": np.zeros((10, 10), dtype=np.float32)} safetensors.save_file(data_to_save, "model.safetensors")

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:`.

breaking The `torch` module was not found, leading to a `ModuleNotFoundError`. This typically means PyTorch is not installed in the execution environment or is not accessible. ↓

fix Ensure that `torch` is installed in your environment. If running in a container, add `pip install torch` (or a specific version) to your Dockerfile or setup script. For specific PyTorch versions and CUDA support, refer to the official PyTorch installation instructions.

breaking The PyTorch library, a core dependency, is not installed or accessible in the execution environment. This typically leads to a `ModuleNotFoundError` when `import torch` is attempted. ↓

fix Ensure that PyTorch is correctly installed in the environment. For `pip`, use `pip install torch`. If running in a container, add `RUN pip install torch` to your Dockerfile or ensure the base image includes it. Verify the Python environment's paths.

Install compatibility verified last tested: 2026-05-12

python os / libc status wheel install import disk

3.10 alpine (musl) wheel - 0.00s 19.5M

3.10 alpine (musl) - - 0.00s 19.5M

3.10 slim (glibc) wheel 1.7s 0.00s 20M

3.10 slim (glibc) - - 0.00s 20M

3.11 alpine (musl) wheel - 0.00s 21.3M

3.11 alpine (musl) - - 0.00s 21.3M

3.11 slim (glibc) wheel 1.8s 0.00s 21M

3.11 slim (glibc) - - 0.00s 21M

3.12 alpine (musl) wheel - 0.00s 13.2M

3.12 alpine (musl) - - 0.00s 13.2M

3.12 slim (glibc) wheel 1.5s 0.00s 13M

3.12 slim (glibc) - - 0.00s 13M

3.13 alpine (musl) wheel - 0.00s 12.9M

3.13 alpine (musl) - - 0.00s 12.8M

3.13 slim (glibc) wheel 1.6s 0.00s 13M

3.13 slim (glibc) - - 0.00s 13M

3.9 alpine (musl) wheel - 0.00s 19.0M

3.9 alpine (musl) - - 0.00s 19.0M

3.9 slim (glibc) wheel 2.0s 0.00s 19M

3.9 slim (glibc) - - 0.00s 19M

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 stale last tested: 2026-04-24

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}")