{"id":702,"library":"safetensors","title":"Safetensors","description":"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.","status":"active","version":"0.7.0","language":"python","source_language":"en","source_url":"https://github.com/huggingface/safetensors","tags":["deep learning","serialization","tensors","huggingface","pytorch","tensorflow","jax"],"install":[{"cmd":"pip install safetensors","lang":"bash","label":"Install Safetensors"}],"dependencies":[{"reason":"Commonly used for tensor manipulation; minimal dependency for related libraries like safestructures.","package":"numpy","optional":true},{"reason":"For PyTorch tensor serialization and deserialization.","package":"torch","optional":true},{"reason":"For TensorFlow tensor serialization and deserialization.","package":"tensorflow","optional":true},{"reason":"For JAX tensor serialization and deserialization.","package":"jax","optional":true},{"reason":"For PaddlePaddle tensor serialization and deserialization.","package":"paddlepaddle","optional":true},{"reason":"Required for the 'torch' extra to manage version compatibility.","package":"packaging","optional":true}],"imports":[{"note":"Main entry point for loading safetensors files generically.","symbol":"safe_open","correct":"from safetensors import safe_open"},{"note":"Framework-specific save function for PyTorch tensors. Similar imports exist for other frameworks (e.g., `.numpy`, `.tensorflow`).","symbol":"save_file","correct":"from safetensors.torch import save_file"},{"note":"Framework-specific load function for PyTorch tensors. Similar imports exist for other frameworks.","symbol":"load_file","correct":"from safetensors.torch import load_file"}],"quickstart":{"code":"import torch\nfrom safetensors.torch import save_file, load_file\nimport os\n\n# Define some dummy tensors\ntensors = {\n    \"weight1\": torch.zeros((1024, 1024)),\n    \"bias\": torch.ones((1024,)),\n    \"embedding\": torch.randn((500, 768))\n}\n\nfile_path = \"my_model.safetensors\"\n\n# Save the tensors to a safetensors file\nsave_file(tensors, file_path)\nprint(f\"Tensors saved to {file_path}\")\n\n# Load the tensors from the safetensors file\nloaded_tensors = load_file(file_path)\nprint(\"Tensors loaded:\")\nfor key, value in loaded_tensors.items():\n    print(f\"  {key}: shape={value.shape}, dtype={value.dtype}\")\n\n# Clean up the created file\nos.remove(file_path)\nprint(f\"Cleaned up {file_path}\")","lang":"python","description":"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."},"warnings":[{"fix":"Ensure tensors are properly aligned or handle `MisalignedByte` exceptions. Be aware of how FP4/FP6 types are represented and accessed.","message":"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.","severity":"breaking","affected_versions":">=0.6.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Be mindful of potential shape changes when working with PyTorch's `float4_e2m1fn_x2` and `safetensors`. Explicitly check tensor shapes after loading.","message":"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.","severity":"gotcha","affected_versions":">=0.6.0"},{"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:`.","message":"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'`).","severity":"deprecated","affected_versions":"0.2.0 and later"},{"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.","message":"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.","severity":"breaking","affected_versions":"All versions"},{"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.","message":"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.","severity":"breaking","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-05-12T17:58:01.245Z","next_check":"2026-06-28T00:00:00.000Z","problems":[{"fix":"pip install safetensors","cause":"The 'safetensors' library is not installed in the current Python environment.","error":"ModuleNotFoundError: No module named '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.","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).","error":"safetensors_rust.SafetensorsError: Error while deserializing header: InvalidHeader"},{"fix":"safetensors.save_file(tensors_dict, 'path/to/your/file.safetensors')","cause":"The `safetensors.save_file` function requires both the dictionary of tensors and the output filename as arguments, but the filename was omitted.","error":"TypeError: safetensors.save_file() missing 1 required positional argument: 'filename'"},{"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).\n\nimport numpy as np\nimport safetensors\n\ndata_to_save = {\"my_tensor\": np.zeros((10, 10), dtype=np.float32)}\nsafetensors.save_file(data_to_save, \"model.safetensors\")","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.","error":"ValueError: expected `tensor` to be dict-like, got type `<class 'str'>`"}],"ecosystem":"pypi","meta_description":null,"install_score":80,"install_tag":"verified","quickstart_score":0,"quickstart_tag":"stale","pypi_latest":"0.7.0","install_checks":{"last_tested":"2026-05-12","tag":"verified","tag_description":"installs cleanly on critical runtimes, fast import, recently tested","results":[{"runtime":"python:3.10-alpine","python_version":"3.10","os_libc":"alpine (musl)","variant":" $EXIT -eq 0 ","exit_code":0,"wheel_type":"wheel","failure_reason":null,"install_time_s":null,"import_time_s":0,"mem_mb":0,"disk_size":"19.5M"},{"runtime":"python:3.10-alpine","python_version":"3.10","os_libc":"alpine (musl)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0,"mem_mb":0,"disk_size":"19.5M"},{"runtime":"python:3.10-slim","python_version":"3.10","os_libc":"slim (glibc)","variant":" $EXIT -eq 0 ","exit_code":0,"wheel_type":"wheel","failure_reason":null,"install_time_s":1.7,"import_time_s":0,"mem_mb":0,"disk_size":"20M"},{"runtime":"python:3.10-slim","python_version":"3.10","os_libc":"slim (glibc)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0,"mem_mb":0,"disk_size":"20M"},{"runtime":"python:3.11-alpine","python_version":"3.11","os_libc":"alpine (musl)","variant":" $EXIT -eq 0 ","exit_code":0,"wheel_type":"wheel","failure_reason":null,"install_time_s":null,"import_time_s":0,"mem_mb":0,"disk_size":"21.3M"},{"runtime":"python:3.11-alpine","python_version":"3.11","os_libc":"alpine (musl)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0,"mem_mb":0,"disk_size":"21.3M"},{"runtime":"python:3.11-slim","python_version":"3.11","os_libc":"slim (glibc)","variant":" $EXIT -eq 0 ","exit_code":0,"wheel_type":"wheel","failure_reason":null,"install_time_s":1.8,"import_time_s":0,"mem_mb":0,"disk_size":"21M"},{"runtime":"python:3.11-slim","python_version":"3.11","os_libc":"slim (glibc)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0,"mem_mb":0,"disk_size":"21M"},{"runtime":"python:3.12-alpine","python_version":"3.12","os_libc":"alpine (musl)","variant":" $EXIT -eq 0 ","exit_code":0,"wheel_type":"wheel","failure_reason":null,"install_time_s":null,"import_time_s":0,"mem_mb":0,"disk_size":"13.2M"},{"runtime":"python:3.12-alpine","python_version":"3.12","os_libc":"alpine (musl)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0,"mem_mb":0,"disk_size":"13.2M"},{"runtime":"python:3.12-slim","python_version":"3.12","os_libc":"slim (glibc)","variant":" $EXIT -eq 0 ","exit_code":0,"wheel_type":"wheel","failure_reason":null,"install_time_s":1.5,"import_time_s":0,"mem_mb":0,"disk_size":"13M"},{"runtime":"python:3.12-slim","python_version":"3.12","os_libc":"slim (glibc)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0,"mem_mb":0,"disk_size":"13M"},{"runtime":"python:3.13-alpine","python_version":"3.13","os_libc":"alpine (musl)","variant":" $EXIT -eq 0 ","exit_code":0,"wheel_type":"wheel","failure_reason":null,"install_time_s":null,"import_time_s":0,"mem_mb":0,"disk_size":"12.9M"},{"runtime":"python:3.13-alpine","python_version":"3.13","os_libc":"alpine (musl)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0,"mem_mb":0,"disk_size":"12.8M"},{"runtime":"python:3.13-slim","python_version":"3.13","os_libc":"slim (glibc)","variant":" $EXIT -eq 0 ","exit_code":0,"wheel_type":"wheel","failure_reason":null,"install_time_s":1.6,"import_time_s":0,"mem_mb":0,"disk_size":"13M"},{"runtime":"python:3.13-slim","python_version":"3.13","os_libc":"slim (glibc)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0,"mem_mb":0,"disk_size":"13M"},{"runtime":"python:3.9-alpine","python_version":"3.9","os_libc":"alpine (musl)","variant":" $EXIT -eq 0 ","exit_code":0,"wheel_type":"wheel","failure_reason":null,"install_time_s":null,"import_time_s":0,"mem_mb":0,"disk_size":"19.0M"},{"runtime":"python:3.9-alpine","python_version":"3.9","os_libc":"alpine (musl)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0,"mem_mb":0,"disk_size":"19.0M"},{"runtime":"python:3.9-slim","python_version":"3.9","os_libc":"slim (glibc)","variant":" $EXIT -eq 0 ","exit_code":0,"wheel_type":"wheel","failure_reason":null,"install_time_s":2,"import_time_s":0,"mem_mb":0,"disk_size":"19M"},{"runtime":"python:3.9-slim","python_version":"3.9","os_libc":"slim (glibc)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0,"mem_mb":0,"disk_size":"19M"}]},"quickstart_checks":{"last_tested":"2026-04-24","tag":"stale","tag_description":"widespread failures or data too old to trust","results":[{"runtime":"python:3.10-alpine","exit_code":1},{"runtime":"python:3.10-slim","exit_code":1},{"runtime":"python:3.11-alpine","exit_code":1},{"runtime":"python:3.11-slim","exit_code":1},{"runtime":"python:3.12-alpine","exit_code":1},{"runtime":"python:3.12-slim","exit_code":1},{"runtime":"python:3.13-alpine","exit_code":1},{"runtime":"python:3.13-slim","exit_code":1},{"runtime":"python:3.9-alpine","exit_code":1},{"runtime":"python:3.9-slim","exit_code":1}]}}