Install & Compatibility
Where this runs
tested against v0.16.1 · 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
py 3.10
✕ build_error
4/5 runs
py 3.11
✕ build_error
4/5 runs
py 3.12
✕ build_error
4/5 runs
py 3.13
✕ build_error
4/5 runs
py 3.9
✕ build_error
3/5 runs
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
SafetensorsStreamer
✓ from runai_model_streamer import SafetensorsStreamer
This quickstart demonstrates how to use `SafetensorsStreamer` to initiate streaming of a model. It creates a dummy `safetensors` file for a runnable example. For actual use, `file_path` should point to your model. When working with cloud storage (S3, GCS, Azure), ensure the respective `runai-model-streamer-*` package is installed and authentication environment variables (e.g., `GOOGLE_APPLICATION_CREDENTIALS` for GCS, `AWS_ACCESS_KEY_ID`, `AWS_SECRET_ACCESS_KEY` for S3, `AZURE_CLIENT_ID` for Azure) are correctly configured. The `stream_file` method starts the streaming process, and `get_tensors()` can then be used to retrieve tensors.
import os
from runai_model_streamer import SafetensorsStreamer
# This is a placeholder for a safetensors file. In a real scenario,
# 'model.safetensors' would be a path to your model file.
# For a runnable example, you might create a dummy file or adapt to a real path.
# If streaming from cloud storage, ensure appropriate backend package is installed
# and environment variables for authentication are set (e.g., GOOGLE_APPLICATION_CREDENTIALS for GCS).
# For local testing, ensure 'model.safetensors' exists or is mocked.
# Example of creating a dummy safetensors file for local quickstart demonstration
try:
from safetensors.torch import save_file
import torch
dummy_tensor = {'tensor_key': torch.randn(10, 10)}
save_file(dummy_tensor, 'model.safetensors')
file_path = "model.safetensors"
print(f"Attempting to stream from: {file_path}")
with SafetensorsStreamer() as streamer:
streamer.stream_file(file_path)
print("Successfully started streaming.")
# In a real scenario, you would then iterate and process tensors:
# for name, tensor in streamer.get_tensors():
# gpu_tensor = tensor.to('cuda:0') # Or another accelerator
# print(f"Streamed tensor: {name}, shape: {gpu_tensor.shape}")
print("Streamer context closed.")
except ImportError:
print("To run this quickstart with a dummy file, install 'safetensors' and 'torch':")
print("pip install safetensors torch")
print("Alternatively, replace 'model.safetensors' with an actual path to your model file.")
except Exception as e:
print(f"An error occurred during quickstart: {e}")
print("Ensure the file_path is correct and necessary system libraries (libcurl4, libssl1.1_1) are installed.")
print("If streaming from cloud storage, verify environment variables for authentication are set.")
Debug
Known issues
breakingThe C++ backend of the streamer requires specific system libraries: `libcurl4` and `libssl1.1_1`. Without these, the Python SDK will not function correctly, leading to runtime errors during model streaming. This is a common installation footgun, especially in minimal container environments.fixEnsure `libcurl4` and `libssl1.1_1` are installed on your system or within your container image. For Debian-based systems, this typically involves `sudo apt-get install libcurl4-openssl-dev libssl-dev` (or similar packages matching the required versions).
affects: All versions
gotchaWhen streaming from cloud object storage (S3, GCS, Azure Blob Storage), specific `runai-model-streamer-*` backend packages (e.g., `runai-model-streamer-gcs`) must be installed in addition to the core `runai-model-streamer` package. Furthermore, proper authentication credentials must be configured via environment variables or service account files for the SDK to access the storage buckets.fixInstall the relevant backend package (`pip install runai-model-streamer-[gcs|s3|azure]`). Configure environment variables such as `GOOGLE_APPLICATION_CREDENTIALS` (for GCS), `AWS_ACCESS_KEY_ID`, `AWS_SECRET_ACCESS_KEY` (for S3), or `AZURE_CLIENT_ID`, `AZURE_TENANT_ID`, `AZURE_CLIENT_SECRET` (for Azure). Refer to the documentation for specific authentication methods.
affects: All versions
deprecatedOlder versions of `runai-model-streamer` used with vLLM, particularly with `tensor-parallel-size > 1`, exhibited pickling errors or issues with distributed streaming across multiple GPUs. This primarily affected distributed loading.fixUpgrade to `runai-model-streamer` version 0.15.x or later. Ensure `vllm[runai]` is updated. When using `vllm serve`, include `--model-loader-extra-config '{"distributed":true}'` for optimal distributed loading from object storage. affects: < 0.15.x (specifically before fixes for #11819 and #130 on GitHub)
gotchaThe `Run:ai Model Streamer` is primarily optimized for the `SafeTensors` file format, which enables efficient zero-copy loading directly from storage. While it may handle other formats, performance benefits are most pronounced with `SafeTensors`.fixStore your AI model weights in the `SafeTensors` format for maximum performance. Tools and libraries like Hugging Face's `safetensors` facilitate saving models in this format.
affects: All versions
gotchaSetting environment variables like `RUNAI_STREAMER_CONCURRENCY` and `RUNAI_STREAMER_MEMORY_LIMIT` can significantly impact performance and resource consumption. Incorrect tuning can lead to suboptimal loading times or out-of-memory issues.fixCarefully tune `RUNAI_STREAMER_CONCURRENCY` (number of OS threads for reading) and `RUNAI_STREAMER_MEMORY_LIMIT` (CPU buffer size) based on your specific model size, available CPU memory, and network bandwidth to object storage. Refer to the official documentation for guidance on these tunable parameters and their impact on performance.
affects: All versions
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'runai_model_streamer'
The 'runai-model-streamer' package is not installed in the current Python environment or is not accessible.
fixpip install runai-model-streamer
ImportError: No module named 's3fs'
You are attempting to stream a model from an S3 bucket, but the necessary 's3fs' backend package was not installed along with 'runai-model-streamer'. (Similar errors occur for 'gcsfs' or 'adlfs' for GCS/Azure respectively).
fixInstall 'runai-model-streamer' with the relevant cloud storage extra: 'pip install runai-model-streamer[s3]' for S3, 'pip install runai-model-streamer[gcs]' for GCS, or 'pip install runai-model-streamer[azure]' for Azure.
safetensors.safetensors_rust.SafetensorsError: Error while deserializing header
The model file specified is either corrupt, not a valid SafeTensors file, or has an invalid header, preventing the streamer from efficiently loading it.
fixVerify the integrity and format of the .safetensors file; ensure it's a legitimate SafeTensors file, or download a fresh, uncorrupted version.
RuntimeError: CUDA error: no CUDA-capable device is detected
The ModelStreamer was configured to load tensors directly onto a CUDA device (e.g., 'device="cuda"') but no NVIDIA GPU with CUDA support is available or properly set up in the system.
fixEnsure a CUDA-enabled GPU is installed with correct drivers, or initialize ModelStreamer with 'device="cpu"' if no GPU is intended for use.
Upgrade
Version history
0.16.1latest on PyPI · released Jul 13, 2026
Audit
Dependencies
libcurl4requiredRequired system library for C++ backend functionality.
libssl1.1_1requiredRequired system library for C++ backend functionality.
runai-model-streamer-gcsoptionalRequired for streaming models from Google Cloud Storage.
runai-model-streamer-s3optionalRequired for streaming models from AWS S3 or S3-compatible object stores.
runai-model-streamer-azureoptionalRequired for streaming models from Azure Blob Storage.
vllmoptionalUsed for accelerated LLM inference; `runai-model-streamer` integrates with vLLM.