Workflow:Huggingface Diffusers Checkpoint Conversion
| Knowledge Sources | |
|---|---|
| Domains | Diffusion_Models, Model_Conversion, Infrastructure |
| Last Updated | 2026-02-13 21:00 GMT |
Overview
End-to-end process for converting model checkpoints from original training formats into the standardized Diffusers format for use with the Hugging Face ecosystem.
Description
This workflow covers the conversion of diffusion model weights from their original research or third-party formats into the Diffusers-compatible format. The Diffusers library uses a standardized model structure where each component (UNet/Transformer, VAE, text encoder, scheduler) is saved separately with consistent configuration files. Conversion scripts handle the remapping of weight names, reshaping of tensors, splitting of monolithic checkpoints into components, and generation of configuration files. The repository includes 86+ conversion scripts covering all major model architectures (Stable Diffusion, Flux, HunyuanVideo, CogVideoX, Wan, Sana, LTX, and many more). The workflow also covers the reverse direction: converting Diffusers models back to original formats for use in other tools (WebUI, ComfyUI).
Usage
Execute this workflow when you have a model checkpoint in a non-Diffusers format (e.g., a .safetensors file from CivitAI, a research checkpoint from a model author's release, or weights from a different framework) and need to use it with the Diffusers library. Also execute when you need to convert Diffusers models to other formats for deployment in alternative inference frameworks. This is a common need when new models are released by research teams before official Diffusers support is added, or when community checkpoints are shared in non-standard formats.
Execution Steps
Step 1: Format Identification
Identify the source format of the checkpoint and determine which conversion path is needed. Examine the checkpoint structure, weight naming conventions, and configuration files to determine the original framework and model architecture.
Key considerations:
- Single-file checkpoints (.safetensors, .ckpt) contain all components in one file
- Multi-file checkpoints may split components across directories
- Weight naming conventions vary by framework (CompVis, Stability, original research code)
- Some checkpoints include configuration files; others require configuration inference
- GGUF files are a separate quantized format with their own loading path
Step 2: Conversion Script Selection
Select the appropriate conversion script from the scripts/ directory based on the source model architecture. Each major model family has a dedicated conversion script that handles the specific weight name mappings and tensor transformations for that architecture.
Key considerations:
- Scripts follow the naming pattern convert_{model}_to_diffusers.py
- Some models have multiple scripts for different variants (e.g., SD3, SDXL, Flux, Flux2)
- Reverse conversion scripts exist for converting back (convert_diffusers_to_original_*)
- LoRA conversion has its own dedicated path (convert_lora_safetensor_to_diffusers.py)
- Megatron-format checkpoints have specialized conversion scripts
Step 3: Weight Mapping Execution
Run the conversion script to transform weight names, reshape tensors, and split the monolithic checkpoint into Diffusers-compatible component directories. The script creates separate directories for each model component with the appropriate configuration files.
Key considerations:
- Weight name mapping translates between naming conventions (e.g., "model.diffusion_model" to "unet")
- Some conversions require tensor reshaping (e.g., merging/splitting attention QKV weights)
- Configuration files (config.json) are generated based on checkpoint structure analysis
- The conversion process may require the full model in memory temporarily
- Validation against reference outputs ensures conversion accuracy
Step 4: Single File Loading Alternative
For quick usage without full conversion, the from_single_file method can load monolithic checkpoint files directly. This approach infers the model configuration from the checkpoint structure and maps weights on-the-fly during loading, avoiding the need for a separate conversion step.
Key considerations:
- from_single_file supports .safetensors and .ckpt formats
- Configuration is inferred automatically but can be overridden
- This path is convenient but full conversion is recommended for production use
- The method works for pipelines, individual models, and VAEs
- Some models require explicit original_config specification for correct loading
Step 5: Validation and Publishing
Validate the converted model by running inference and comparing outputs against the original checkpoint. Once validated, the converted model can be pushed to the Hugging Face Hub in the standard Diffusers format for community reuse.
Key considerations:
- Compare generated images between original and converted models for visual equivalence
- Verify numerical similarity of intermediate activations if possible
- Include conversion metadata (source, script version) in the model card
- Standard Diffusers format enables seamless integration with all library features
- The converted model benefits from all Diffusers optimizations (offloading, compilation, quantization)