Registry / ai-ml / fastsafetensors

fastsafetensors

JSON →
library0.3.2pypypiunverified

fastsafetensors is a Python library designed for high-performance loading of safetensors models, particularly optimized for GPU environments (CUDA, ROCm). It aims to offer faster loading times compared to the standard `safetensors` library for large models. The current version is `0.2.2`, and it maintains an active release cadence with frequent bug fixes and performance improvements.

pip install fastsafetensors
INSTALL
IMPORT
SIG · FASTSAFETENSORS
F
fastsafetensors
ai-mlpythonv0.3.2
Install
2.9s avg
Import
Disk
37MB
Pass rate
5/ 10
Env Coverage5 / 10
glibc
3.93.13
musl
3.93.13
Install & Compatibility
Where this runs
tested against v0.3.2 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
musl
py 3.103.910 runs
build_error
glibc
py 3.103.910 runs
installs and imports cleanly · install 2.9s · import 0.000s · 39MB
37MB installed
● package 37MB
Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

FastSafetensorsFile
from fastsafetensors import FastSafetensorsFile
from fastsafetensors import FastSafetensorsFile

This quickstart demonstrates how to create a dummy safetensors file using the standard `safetensors` library, then load it with `fastsafetensors.FastSafetensorsFile`. It shows how to inspect the file's metadata and how to lazily load individual tensors by accessing them like dictionary items. Note that `torch` is used here for tensor creation and loading, implying it should be installed for this specific example.

import torch from safetensors.torch import save_file from fastsafetensors import FastSafetensorsFile import os # 1. Create a dummy safetensors file for demonstration dummy_data = { "layer1.weight": torch.randn(128, 64), "layer1.bias": torch.zeros(128), "layer2.weight": torch.ones(64, 32) } dummy_file_path = "dummy_model.safetensors" save_file(dummy_data, dummy_file_path) print(f"Created dummy safetensors file: {dummy_file_path}\n") # 2. Load the safetensors file using FastSafetensorsFile try: fsf = FastSafetensorsFile(dummy_file_path) # 3. Inspect tensor metadata (does not load data into memory) print("Tensors available in the file (metadata only):") for name, metadata in fsf.get_tensors().items(): print(f" - {name}: {metadata}") # 4. Access a specific tensor (this triggers loading for that tensor) tensor_name = "layer1.weight" loaded_tensor = fsf[tensor_name] print(f"\nSuccessfully loaded '{tensor_name}':") print(f" Type: {type(loaded_tensor)}") print(f" Shape: {loaded_tensor.shape}") print(f" First 5 elements:\n{loaded_tensor.flatten()[:5]}\n") # Access another tensor print(f"Accessing 'layer2.weight' (shape: {fsf['layer2.weight'].shape})\n") except Exception as e: print(f"An error occurred: {e}") finally: # 5. Clean up the dummy file if os.path.exists(dummy_file_path): os.remove(dummy_file_path) print(f"Cleaned up dummy file: {dummy_file_path}")
Debug
Known issues
gotcha`fastsafetensors` is designed for *loading* safetensors files efficiently, particularly on GPU. It does not provide functionality to *save* safetensors files. For saving, you should use the core `safetensors` library (e.g., `safetensors.torch.save_file`).
fix
Use `safetensors` for saving models: `from safetensors.torch import save_file; save_file(model_state, 'model.safetensors')`.
affects: All versions
gotcha`FastSafetensorsFile` implements lazy loading. Tensors are not fully loaded into memory when the file is opened or when `get_tensors()` is called. They are loaded only when accessed (e.g., `fsf['tensor_name']`). This design optimizes memory usage and startup time but might surprise users expecting eager loading.
fix
Be aware that `fsf.get_tensors()` returns metadata (name, shape, dtype, data_offsets), not the actual tensor data. Access specific tensors by key (e.g., `my_tensor = fsf['my_key']`) to trigger their loading.
affects: All versions
gotchaTo leverage `fastsafetensors` for specific deep learning frameworks (PyTorch, TensorFlow, PaddlePaddle), those frameworks must be installed separately. `fastsafetensors` does not include them as direct dependencies but will convert loaded data into their respective tensor types if available.
fix
Install the necessary framework (e.g., `pip install torch`, `pip install tensorflow`, `pip install paddlepaddle`) if you intend to work with framework-specific tensor objects.
affects: All versions
deprecatedOlder versions (0.2.0 and prior) had known issues with CUDA device initialization and stream synchronization, potentially leading to incorrect behavior or suboptimal performance in multi-GPU or complex asynchronous operations.
fix
Upgrade to `fastsafetensors` version `0.2.1` or newer to benefit from critical bug fixes related to CUDA stream synchronization and device initialization.
affects: <=0.2.0
Upgrade
Version history
0.3.2latest on PyPI · released Jun 4, 2026
Audit
Dependencies
safetensorsrequiredCore library for safetensors format specification and basic operations.
torchoptionalRequired to load tensors as PyTorch `torch.Tensor` objects.
tensorflowoptionalRequired to load tensors as TensorFlow `tf.Tensor` objects.
paddlepaddleoptionalRequired to load tensors as PaddlePaddle `paddle.Tensor` objects.
Agent activity
16 hits · last 30 days
node
14
OpenAI (training)
1
Resources
fastsafetensors — pip install fastsafetensors · libregistry