[Modular] Save Modular Pipeline weights to Hub by DN6 · Pull Request #13168 · huggingface/diffusers

DN6 · 2026-02-20T14:01:44Z

What does this PR do?

Enable modular pipelines to save model weights to the Hub. Previously, only configs were saved. Note that if individual components are loaded from external repos, their model configs will continue to reference those repos. I've added an optional overwrite_modular_index flag to rewrite component configs so they point to the destination repo instead.

Fixes # (issue)

Before submitting

This PR fixes a typo or improves the docs (you can dismiss the other checks if that's the case).
Did you read the contributor guideline?
Did you read our philosophy doc (important for complex PRs)?
Was this discussed/approved via a GitHub issue or the forum? Please add a link to it if that's the case.
Did you make sure to update the documentation with your changes? Here are the
documentation guidelines, and
here are tips on formatting docstrings.
Did you write any new necessary tests?

Who can review?

Anyone in the community is free to review the PR once the tests have passed. Feel free to tag
members/contributors who may be interested in your PR.

HuggingFaceDocBuilderDev · 2026-02-20T14:16:53Z

The docs for this PR live here. All of your documentation changes will be reflected on that endpoint. The docs are available until 30 days after the last update.

sayakpaul

I left some comments. Let's also add some simple tests:

Checking if the params are being serialized (just checking if the checkpoint files exist is enough)?
modular_model_index.json reflects the repository locations properly?

sayakpaul · 2026-02-20T14:15:52Z

src/diffusers/modular_pipelines/modular_pipeline.py

+                If expressed as an integer, the unit is bytes.
+            push_to_hub (`bool`, *optional*, defaults to `False`):
+                Whether to push the pipeline to the Hugging Face model hub after saving it.
+            **kwargs: Additional keyword arguments passed along to the push to hub method.


Should we document what is allowed in the kwargs? overwrite_modular_index deserves some documentation IMO.

Will add the necessary doc.

sayakpaul · 2026-02-20T14:16:40Z

src/diffusers/modular_pipelines/modular_pipeline.py

+                if component_spec.default_creation_method != "from_pretrained":
+                    continue


Could you explain what this is doing?

When saving a Modular Pipeline, its components in modular_model_index.json may reference repos different from the destination repo.

e.g. The text_encoder component in this model repo points to OzzyGT/Qwen3-4B-bnb-4bit while the other components point to black-forest-labs/FLUX.2-klein-4B".
https://huggingface.co/diffusers/FLUX.2-klein-4B-modular/blob/main/modular_model_index.json

None of these components actually point to the reference repo diffusers/FLUX.2-klein-4B-modular. The overwrite_modular_index parameter updates the modular index file so that all component references point to the repo specified by repo_id.

Understood but I don't find any relation of this to the condition if component_spec.default_creation_method != "from_pretrained":. For a remote repo ID, we would still rely on from_pretrained() no?

The overwrite_modular_index block only touches from_pretrained components because only they have pretrained_model_name_or_path entries in the config pointing to external Hub repos. Anything that's not created with from_pretrained is skipped.

sayakpaul · 2026-02-20T14:17:50Z

src/diffusers/modular_pipelines/modular_pipeline.py


-            # Create a new empty model card and eventually tag it
+        if push_to_hub:
+            card_content = generate_modular_model_card_content(self.blocks)


Is this conditioned on the above changes? If not, maybe we can keep it in the earlier position?

src/diffusers/modular_pipelines/modular_pipeline.py

sayakpaul · 2026-02-20T14:23:36Z

src/diffusers/modular_pipelines/modular_pipeline.py

+        repo_id = kwargs.pop("repo_id", save_directory.split(os.path.sep)[-1])
+
+        for component_name, component_spec in self._component_specs.items():
+            sub_model = getattr(self, component_name, None)


(nit):

Suggested change

sub_model = getattr(self, component_name, None)

component = getattr(self, component_name, None)

Not all components need to models.

sayakpaul · 2026-02-20T14:24:40Z

src/diffusers/modular_pipelines/modular_pipeline.py

+                if variant is not None and "variant" in component_spec_dict:
+                    component_spec_dict["variant"] = variant
+
+                self.register_to_config(**{component_name: (library, class_name, component_spec_dict)})


I am not too sure about the objective of this block. What happens if its corresponding model_cls doesn't have the save method we support through LOADABLE_CLASSES?

Or is this unrelated?

See reply: https://github.com/huggingface/diffusers/pull/13168/changes#r2839538866

yiyixuxu

thanks!
i left one comment!

yiyixuxu · 2026-02-25T23:25:12Z

src/diffusers/modular_pipelines/modular_pipeline.py


-            # Generate modular pipeline card content
-            card_content = generate_modular_model_card_content(self.blocks)
+        if overwrite_modular_index:


very nice!
can we handle the case for custom/local models in this PR as well? I think it fits naturally in this PR

Basically, if users update a pipeline with a custom model (e.g. one loaded from a local path, or a custom model that they would want to host in the same repo with trust_remote_code like https://huggingface.co/krea/krea-realtime-video/tree/main/transformer) and they should be able save it to the pipeline repo even when overwrite_modular_index= False :

# load a custom model from local path custom_model = AutoModel.from_pretrained("/path/to/your/local/model") pipe.update_components(custom_model=custom_model) pipe.save_pretrained("my-repo", push_to_hub=True)

in the modular_model_index, the pretrained_model_name_or_path should refer to my-repo

For components that don't have a _diffusers_load_id (i.e. no Hub reference), save_pretrained should automatically:

Save the weights to the repo (you already did this)

Update the modular_model_index.json to point locally (this need to be implemented even when overewrite_modular_index=False

additionally, I think we could use "." as the convention for local references in modular_model_index.json (huggingface/blog#3278 (comment)) but that should be a follow-up PR if we decided to do it!

and then, we can remove the warning in update_components for missing _diffusers_load_id should be removed: https://github.com/huggingface/diffusers/blob/main/src/diffusers/modular_pipelines/modular_pipeline.py#L2150

logger.warning( f"ModularPipeline.update_components: {name} has no valid _diffusers_load_id. " f"This will result in empty loading spec, use ComponentSpec.load() for proper specs" )

because this now become a completely normal workflow (load custom model → update pipeline → save)!

DN6 added 2 commits February 20, 2026 14:04

update

71ce634

update

e340b52

DN6 requested a review from yiyixuxu February 20, 2026 14:02

update

c167fe3

sayakpaul reviewed Feb 20, 2026

View reviewed changes

update

a9269d2

yiyixuxu reviewed Feb 25, 2026

View reviewed changes

update

2099586

		if component_spec.default_creation_method != "from_pretrained":
		continue

	sub_model = getattr(self, component_name, None)
	component = getattr(self, component_name, None)

Conversation

DN6 commented Feb 20, 2026

What does this PR do?

Before submitting

Who can review?

Uh oh!

HuggingFaceDocBuilderDev commented Feb 20, 2026

Uh oh!

sayakpaul left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

yiyixuxu left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants