Implementation:Huggingface Diffusers Single File Loadable Classes

Field	Value
Type	Pattern Doc
Overview	The SINGLE_FILE_LOADABLE_CLASSES registry that maps Diffusers model classes to their conversion functions, enabling automatic dispatch during from_single_file loading
Domains	Model Conversion, Registry Pattern
Workflow	Checkpoint_Conversion
Related Principle	Huggingface_Diffusers_Conversion_Script_Selection
Source	src/diffusers/loaders/single_file_model.py:L78-L197
Last Updated	2026-02-13 00:00 GMT

Code Reference

SINGLE_FILE_LOADABLE_CLASSES Registry

Source: src/diffusers/loaders/single_file_model.py:L78-L197

SINGLE_FILE_LOADABLE_CLASSES = {
    "StableCascadeUNet": {
        "checkpoint_mapping_fn": convert_stable_cascade_unet_single_file_to_diffusers,
    },
    "UNet2DConditionModel": {
        "checkpoint_mapping_fn": convert_ldm_unet_checkpoint,
        "config_mapping_fn": create_unet_diffusers_config_from_ldm,
        "default_subfolder": "unet",
        "legacy_kwargs": {
            "num_in_channels": "in_channels",
        },
    },
    "AutoencoderKL": {
        "checkpoint_mapping_fn": convert_ldm_vae_checkpoint,
        "config_mapping_fn": create_vae_diffusers_config_from_ldm,
        "default_subfolder": "vae",
    },
    "FluxTransformer2DModel": {
        "checkpoint_mapping_fn": convert_flux_transformer_checkpoint_to_diffusers,
        "default_subfolder": "transformer",
    },
    "WanTransformer3DModel": {
        "checkpoint_mapping_fn": convert_wan_transformer_to_diffusers,
        "default_subfolder": "transformer",
    },
    "WanVACETransformer3DModel": {
        "checkpoint_mapping_fn": convert_wan_transformer_to_diffusers,
        "default_subfolder": "transformer",
    },
    "AutoencoderKLWan": {
        "checkpoint_mapping_fn": convert_wan_vae_to_diffusers,
        "default_subfolder": "vae",
    },
    "HunyuanVideoTransformer3DModel": {
        "checkpoint_mapping_fn": convert_hunyuan_video_transformer_to_diffusers,
        "default_subfolder": "transformer",
    },
    # ... (25+ total entries for all supported model classes)
}

_get_single_file_loadable_mapping_class

Source: src/diffusers/loaders/single_file_model.py:L208-L216

def _get_single_file_loadable_mapping_class(cls):
    diffusers_module = importlib.import_module(__name__.split(".")[0])
    for loadable_class_str in SINGLE_FILE_LOADABLE_CLASSES:
        loadable_class = getattr(diffusers_module, loadable_class_str)
        if issubclass(cls, loadable_class):
            return loadable_class_str
    return None

_should_convert_state_dict_to_diffusers

Source: src/diffusers/loaders/single_file_model.py:L200-L205

def _should_convert_state_dict_to_diffusers(model_state_dict, checkpoint_state_dict):
    model_state_dict_keys = set(model_state_dict.keys())
    checkpoint_state_dict_keys = set(checkpoint_state_dict.keys())
    is_subset = model_state_dict_keys.issubset(checkpoint_state_dict_keys)
    is_match = model_state_dict_keys == checkpoint_state_dict_keys
    return not (is_subset and is_match)

Registry Entry Structure

Key	Type	Required	Description
checkpoint_mapping_fn	Callable	Yes	Function that converts checkpoint dict to Diffusers format
config_mapping_fn	Callable	No	Function that converts original YAML config to Diffusers config
default_subfolder	str	No	Subfolder in pretrained model repo (e.g., "transformer", "vae")
legacy_kwargs	dict	No	Mapping of deprecated kwargs to current kwargs

I/O Contract

_get_single_file_loadable_mapping_class

Inputs:

• cls: The model class that from_single_file was called on (e.g., WanTransformer3DModel)

Outputs:

• str | None: The registry key name if found (e.g., "WanTransformer3DModel"), or None if the class is not supported

_should_convert_state_dict_to_diffusers

Inputs:

• model_state_dict: Expected state dict from the initialized Diffusers model
• checkpoint_state_dict: Actual state dict from the loaded checkpoint

Outputs:

• bool: True if conversion is needed, False if the checkpoint is already in Diffusers format

Supported Model Classes

Category	Model Classes	Count
Image Transformers	FluxTransformer2DModel, SD3Transformer2DModel, ChromaTransformer2DModel, AuraFlowTransformer2DModel, Lumina2Transformer2DModel, SanaTransformer2DModel, HiDreamImageTransformer2DModel, ZImageTransformer2DModel, Flux2Transformer2DModel, QwenImageTransformer2DModel	10
Video Transformers	WanTransformer3DModel, WanVACETransformer3DModel, WanAnimateTransformer3DModel, HunyuanVideoTransformer3DModel, MochiTransformer3DModel, LTXVideoTransformer3DModel, CosmosTransformer3DModel, LTX2VideoTransformer3DModel	8
UNets	UNet2DConditionModel, StableCascadeUNet	2
VAEs	AutoencoderKL, AutoencoderKLWan, AutoencoderDC, AutoencoderKLLTXVideo, AutoencoderKLLTX2Video, AutoencoderKLLTX2Audio	6
ControlNets	ControlNetModel, SparseControlNetModel, ZImageControlNetModel	3
Motion	MotionAdapter	1

Usage Examples

Checking if a Model Class is Supported

from diffusers.loaders.single_file_model import _get_single_file_loadable_mapping_class
from diffusers import WanTransformer3DModel

mapping = _get_single_file_loadable_mapping_class(WanTransformer3DModel)
# Returns: "WanTransformer3DModel"

Adding a New Model to the Registry

# In single_file_model.py, add to SINGLE_FILE_LOADABLE_CLASSES:
SINGLE_FILE_LOADABLE_CLASSES = {
    # ... existing entries ...
    "NewModel3DModel": {
        "checkpoint_mapping_fn": convert_new_model_to_diffusers,
        "default_subfolder": "transformer",
    },
}

Related Pages

• Huggingface_Diffusers_Conversion_Script_Selection (principle for this implementation) - Theory of the registry pattern
• Huggingface_Diffusers_Infer_Model_Type (used alongside) - Model type inference feeds config selection
• Huggingface_Diffusers_Convert_Checkpoint_To_Diffusers (dispatched by this) - Conversion functions registered here
• Huggingface_Diffusers_From_Single_File (uses this) - from_single_file looks up the registry

Principle:Huggingface_Diffusers_Conversion_Script_Selection