Implementation:Huggingface Diffusers Save Pretrained And Push

Field	Value
Type	API Doc
Overview	Saving pipeline components to local directory with save_pretrained and uploading to HuggingFace Hub with push_to_hub
Domains	Model Deployment, HuggingFace Hub
Workflow	Checkpoint_Conversion
Related Principle	Huggingface_Diffusers_Model_Publishing
Source	src/diffusers/pipelines/pipeline_utils.py:L240-L371, src/diffusers/utils/hub_utils.py:L506-L580
Last Updated	2026-02-13 00:00 GMT

Code Reference

DiffusionPipeline.save_pretrained

Source: src/diffusers/pipelines/pipeline_utils.py:L240-L371

def save_pretrained(
    self,
    save_directory: str | os.PathLike,
    safe_serialization: bool = True,
    variant: str | None = None,
    max_shard_size: int | str | None = None,
    push_to_hub: bool = False,
    **kwargs,
):
    """Save all saveable variables of the pipeline to a directory."""
    model_index_dict = dict(self.config)
    model_index_dict.pop("_class_name", None)
    model_index_dict.pop("_diffusers_version", None)

    if push_to_hub:
        repo_id = kwargs.pop("repo_id", save_directory.split(os.path.sep)[-1])
        repo_id = create_repo(repo_id, exist_ok=True, private=kwargs.pop("private", None),
                             token=kwargs.pop("token", None)).repo_id

    expected_modules, optional_kwargs = self._get_signature_keys(self)

    for pipeline_component_name in model_index_dict.keys():
        sub_model = getattr(self, pipeline_component_name)
        model_cls = sub_model.__class__

        # Find the correct save method from LOADABLE_CLASSES
        save_method_name = None
        for library_name, library_classes in LOADABLE_CLASSES.items():
            for base_class, save_load_methods in library_classes.items():
                class_candidate = getattr(library, base_class, None)
                if class_candidate is not None and issubclass(model_cls, class_candidate):
                    save_method_name = save_load_methods[0]
                    break

        save_method = getattr(sub_model, save_method_name)
        save_kwargs = {}
        if "safe_serialization" in inspect.signature(save_method).parameters:
            save_kwargs["safe_serialization"] = safe_serialization
        if "variant" in inspect.signature(save_method).parameters:
            save_kwargs["variant"] = variant
        if "max_shard_size" in inspect.signature(save_method).parameters and max_shard_size:
            save_kwargs["max_shard_size"] = max_shard_size

        save_method(os.path.join(save_directory, pipeline_component_name), **save_kwargs)

    self.save_config(save_directory)

    if push_to_hub:
        model_card = load_or_create_model_card(repo_id, token=token, is_pipeline=True)
        model_card = populate_model_card(model_card)
        model_card.save(os.path.join(save_directory, "README.md"))
        self._upload_folder(save_directory, repo_id, token=token, ...)

PushToHubMixin.push_to_hub

Source: src/diffusers/utils/hub_utils.py:L506-L580

def push_to_hub(
    self,
    repo_id: str,
    commit_message: str | None = None,
    private: bool | None = None,
    token: str | None = None,
    create_pr: bool = False,
    safe_serialization: bool = True,
    variant: str | None = None,
    subfolder: str | None = None,
) -> str:
    """Upload model, scheduler, or pipeline files to HuggingFace Hub."""
    repo_id = create_repo(repo_id, private=private, token=token, exist_ok=True).repo_id

    if not subfolder:
        model_card = load_or_create_model_card(repo_id, token=token)
        model_card = populate_model_card(model_card)

    with tempfile.TemporaryDirectory() as tmpdir:
        self.save_pretrained(tmpdir, safe_serialization=safe_serialization, variant=variant)
        if not subfolder:
            model_card.save(os.path.join(tmpdir, "README.md"))
        return self._upload_folder(tmpdir, repo_id, token=token,
                                   commit_message=commit_message, create_pr=create_pr,
                                   subfolder=subfolder)

Import

# These methods are available on all Diffusers pipelines and models:
from diffusers import WanPipeline, DiffusionPipeline

# save_pretrained is a method on pipeline/model instances
# push_to_hub is a method on pipeline/model instances

Key Parameters

save_pretrained

Parameter	Type	Description	Default
save_directory	PathLike	Local directory path	(required)
safe_serialization	bool	Use safetensors format	True
variant	None	Weight file variant (e.g., "fp16")	None
max_shard_size	str | None	Max shard file size (e.g., "5GB")	None
push_to_hub	bool	Push to Hub after saving	False

push_to_hub

Parameter	Type	Description	Default
repo_id	str	Hub repository ID (e.g., "my-org/my-model")	(required)
commit_message	None	Git commit message	"Upload {object}"
private	None	Make repo private	None (org default)
token	None	HuggingFace auth token	None (from login)
create_pr	bool	Create PR instead of direct commit	False
safe_serialization	bool	Use safetensors format	True
variant	None	Weight variant	None
subfolder	None	Upload to a subfolder in the repo	None

I/O Contract

save_pretrained

Inputs:

• Pipeline or model instance with loaded weights
• Target directory path

Outputs:

• Directory with standard Diffusers structure:

save_directory/
  model_index.json          # Pipeline config
  scheduler/
    scheduler_config.json
  tokenizer/
    tokenizer_config.json, vocab.json, ...
  text_encoder/
    config.json
    model.safetensors (or model.safetensors.index.json + shards)
  transformer/
    config.json
    diffusion_pytorch_model.safetensors
  vae/
    config.json
    diffusion_pytorch_model.safetensors

push_to_hub

Inputs:

• Model or pipeline instance
• Repository ID

Outputs:

• str: URL of the uploaded repository or commit

External Dependencies

• huggingface_hub (for create_repo, file uploading)
• safetensors (for serialization)

Usage Examples

Saving a Converted Pipeline Locally

import torch
from diffusers import WanPipeline, AutoencoderKLWan

# Load and set up pipeline
model_id = "Wan-AI/Wan2.1-T2V-14B-Diffusers"
vae = AutoencoderKLWan.from_pretrained(model_id, subfolder="vae", torch_dtype=torch.float32)
pipe = WanPipeline.from_pretrained(model_id, vae=vae, torch_dtype=torch.bfloat16)

# Save locally
pipe.save_pretrained("./my_wan_pipeline", safe_serialization=True)

Pushing a Converted Model to Hub

# Push entire pipeline
pipe.push_to_hub("my-org/wan-14b-converted", private=True, token="hf_...")

# Or push a single component
pipe.transformer.push_to_hub("my-org/wan-14b-transformer", subfolder="transformer")

Converting from Single File and Publishing

from diffusers import FluxTransformer2DModel
import torch

# Load from original checkpoint
model = FluxTransformer2DModel.from_single_file(
    "flux1-dev.safetensors",
    torch_dtype=torch.bfloat16,
)

# Validate by running inference...

# Save in Diffusers format
model.save_pretrained("./flux-dev-diffusers", safe_serialization=True)

# Push to Hub
model.push_to_hub("my-org/flux-dev-diffusers")

Saving with Sharding for Large Models

# For models > 5GB, shard the weights
pipe.save_pretrained(
    "./large_model",
    safe_serialization=True,
    max_shard_size="5GB",
)
# Produces: diffusion_pytorch_model-00001-of-00003.safetensors, etc.

Related Pages

• Huggingface_Diffusers_Model_Publishing (principle for this implementation) - Theory of model validation and publishing
• Huggingface_Diffusers_From_Single_File (prerequisite) - Loading the model to be saved/published
• Huggingface_Diffusers_Video_Pipeline_From_Pretrained (loads saved models) - from_pretrained loads the saved directory structure

Principle:Huggingface_Diffusers_Model_Publishing