Registry / ai-ml / spandrel

spandrel

JSON →
library0.4.2pypypi✓ verified 23d ago

Spandrel is a Python library that provides support for loading and running pre-trained PyTorch models, particularly those used in AI Super-Resolution, restoration, and inpainting. It automatically detects the model architecture and hyperparameters from various model file types, including `.pth`, `.pt`, `.ckpt`, and `.safetensors`. The current version is 0.4.2, and it follows an active release cadence with updates often accompanied by the `spandrel_extra_arches` package for models with restrictive licenses.

pip install spandrel
INSTALL
IMPORT
SIG · SPANDREL
S
spandrel
ai-mlpythonv0.4.2
Install
67.9s avg
Import
13589ms
Disk
4890MB
Pass rate
4/ 10
Env Coverage4 / 10
glibc
3.93.13
musl
3.93.13
Install & Compatibility
Where this runs
tested against v0.4.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
glibc
py 3.10
✕ build_error
✓ 78.25s
py 3.11
✕ build_error
✓ 74.75s
py 3.12
✕ build_error
✓ 61.15s
py 3.13
✕ build_error
✓ 57.5s
py 3.9
✕ build_error
✕ timeout
4890MB installed
● package 4890MB
Code
Verified usage

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

ModelLoader
from spandrel import ModelLoader
from spandrel.__helpers import ModelLoader
Internal modules like `__helpers` are not part of the public API and should not be imported directly.

This quickstart demonstrates how to load a pre-trained PyTorch model using `ModelLoader.load_from_file`. The `ModelLoader` automatically detects the architecture and provides a unified `ModelDescriptor` object. The example includes a placeholder for a model path and demonstrates how to interact with the loaded model, including accessing metadata and attempting a forward pass with a dummy tensor input. Users should replace the placeholder path with a real `.pth` model file.

import os import torch from spandrel import ModelLoader # This is a placeholder for a real .pth model file. # In a real scenario, you would have a path to a pre-trained PyTorch model. # For demonstration, we'll simulate loading a non-existent file. # Replace 'path/to/your/model.pth' with an actual model file path. # A common practice is to download models from official repositories. model_path = os.environ.get('SPANDREL_MODEL_PATH', 'path/to/your/model.pth') # Ensure the directory for the dummy model exists if needed for testing # For a real quickstart, the model_path would point to an existing file. if not os.path.exists(model_path): print(f"[NOTE]: Model file not found at '{model_path}'. This example requires a valid .pth model file.\n") print("You can download a sample model, e.g., from a Super-Resolution project, and update 'model_path'.") # Simulate a dummy model for demonstration purposes if no file exists # This part would typically not be in a quickstart as it expects a real file. # For the purpose of making this runnable *without* an actual file, # we'll create a minimal placeholder for the ModelLoader.load_from_file call to fail gracefully. try: # Attempt to load, expecting failure without a real file model = ModelLoader.load_from_file(model_path) # If it miraculously works (e.g., user provided a path to a dummy file), # then proceed to describe interaction. print(f"Successfully loaded model: {model.name}") # ModelDescriptor objects (like ImageModelDescriptor) are wrappers around the actual PyTorch model. # They provide a unified interface. # The actual forward pass depends on the model type. # For an ImageModelDescriptor, input is typically a torch.Tensor (batch, channels, height, width). # dummy_input = torch.randn(1, 3, 256, 256) # Example input for an image model # output = model(dummy_input) # print(f"Model output shape: {output.shape}") except FileNotFoundError: print("Failed to load model as expected, because the file does not exist.") print("Please provide a real .pth model path for a functional example.") except Exception as e: print(f"An error occurred during model loading: {e}") else: try: model = ModelLoader.load_from_file(model_path) print(f"Successfully loaded model: {model.name} (architecture: {model.architecture.name})") # Example of accessing metadata if hasattr(model, 'scale'): print(f"Model scale: {model.scale}x") if hasattr(model, 'upscale_latent'): # Specific to certain architectures print(f"Upscale latent: {model.upscale_latent}") # Note: ImageModelDescriptor will NOT convert an image to a tensor. # You need to provide a pre-processed tensor. # For demonstration, we'll create a dummy input tensor if the model expects one. if 'Image' in str(type(model)) or 'Upscaler' in str(type(model)): # Assuming a common image input format: NCHW (batch, channels, height, width) dummy_input = torch.randn(1, 3, 128, 128) # Example: batch size 1, 3 channels, 128x128 image print(f"Attempting forward pass with dummy input shape: {dummy_input.shape}") try: output = model(dummy_input) print(f"Model forward pass successful. Output shape: {output.shape}") except Exception as e: print(f"Error during model forward pass with dummy input: {e}") print("The actual input shape and type depend on the specific model architecture.") else: print("Model type not recognized for dummy image input. Skipping forward pass.") except Exception as e: print(f"Error loading or interacting with model from '{model_path}': {e}")
Debug
Known issues
gotchaLoading `.pth` files using Python's `pickle` module, which `spandrel` utilizes, poses a security risk due to its vulnerability to arbitrary code execution. `spandrel` attempts to mitigate this by only deserializing certain data types, but it does not fully eliminate the risk. Only load `.pth` files from trusted sources.
fix
Ensure all `.pth` model files originate from reputable and verified sources. Exercise caution with untrusted `.pth` files.
affects: All versions
gotchaThe `spandrel` package contains architectures with permissive licenses (MIT, Apache 2.0, public domain). For architectures with more restrictive licenses (e.g., non-commercial), you need to install `spandrel_extra_arches`. Be aware of the licensing implications of `spandrel_extra_arches` for commercial or closed-source projects.
fix
Install `spandrel_extra_arches` if you need support for models with restrictive licenses and review the licenses of individual architectures within that package for compliance with your project's use case.
affects: All versions
breakingStarting from v0.4.0, all architectures in `spandrel` (and `spandrel_extra_arches`) require keyword arguments for their `load` methods. This change improves clarity and prevents errors when calling architecture-specific loading functions.
fix
When defining or calling architecture `load` methods, ensure all arguments are passed as keyword arguments (e.g., `model_loader.load(state_dict=state_dict, key='value')` instead of `model_loader.load(state_dict, 'value')`).
affects: >=0.4.0
gotchaThe `ModelDescriptor` and its variants (e.g., `ImageModelDescriptor`) provided by `spandrel` do not perform image-to-tensor conversion. You must pre-process your image data into a `torch.Tensor` with the correct shape and data type before passing it to the model for inference.
fix
Manually convert your image data (e.g., using libraries like Pillow and torchvision.transforms) into a `torch.Tensor` matching the expected input format (e.g., `(batch_size, channels, height, width)` and `torch.float32`) before calling the loaded model.
affects: All versions
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'spandrel'
The 'spandrel' package is not installed in the Python environment.
fix
Install the package using pip: 'pip install spandrel'.
ImportError: cannot import name 'ModelLoader' from 'spandrel'
The 'ModelLoader' class is not available in the 'spandrel' module, possibly due to an outdated version.
fix
Ensure you have the latest version of spandrel installed: 'pip install --upgrade spandrel'.
AttributeError: module 'spandrel' has no attribute 'ImageModelDescriptor'
The 'ImageModelDescriptor' attribute is missing, likely due to an incorrect import or outdated package version.
fix
Verify the correct import statement and update spandrel: 'pip install --upgrade spandrel'.
TypeError: 'NoneType' object is not callable
Attempting to call a function or method that is None, possibly due to a failed model load.
fix
Check if the model was loaded successfully before calling its methods.
ValueError: Unsupported model architecture
The model file corresponds to an architecture not supported by spandrel.
fix
Ensure the model architecture is supported or update spandrel to the latest version.
Upgrade
Version history
0.4.2latest on PyPI · released Feb 21, 2026
Audit
Dependencies
torchrequiredCore dependency for PyTorch models.
spandrel_extra_archesoptionalProvides support for additional model architectures with restrictive licenses (e.g., non-commercial). Not installed by default with `spandrel`.
Agent activity
25 hits · last 30 days
node
20
Amazon
1
OpenAI (training)
1
Resources
spandrel — pip install spandrel · libregistry