From 62e985dd017cb22c4642f71082c358be72a35f0d Mon Sep 17 00:00:00 2001 From: sayakpaul Date: Mon, 19 Oct 2026 16:03:32 +0530 Subject: [PATCH 1/3] discourage cross repo references for modular repos. --- docs/source/en/modular_diffusers/modular_pipeline.md | 11 ++++++----- 1 file changed, 6 insertions(+), 5 deletions(-) diff --git a/docs/source/en/modular_diffusers/modular_pipeline.md b/docs/source/en/modular_diffusers/modular_pipeline.md index e234a8aa4aae..002d9155ba21 100644 --- a/docs/source/en/modular_diffusers/modular_pipeline.md +++ b/docs/source/en/modular_diffusers/modular_pipeline.md @@ -212,7 +212,7 @@ pipeline = ModularPipeline.from_pretrained( ) ``` -**A modular repository.** These repositories contain a `modular_model_index.json` that specifies where to load each component from — the components can come from different repositories and the modular repository itself may not contain any model weights. For example, [diffusers/flux2-bnb-4bit-modular](https://huggingface.co/diffusers/flux2-bnb-4bit-modular) loads a quantized transformer from one repository and the remaining components from another. See [Modular repository](#modular-repository) for more details on the format. +**A modular repository.** These repositories contain a `modular_model_index.json` that specifies where to load each component from. For new repositories, prefer storing the components in the modular repository itself. Cross-repository references are supported when components are intentionally hosted elsewhere, as in [diffusers/flux2-bnb-4bit-modular](https://huggingface.co/diffusers/flux2-bnb-4bit-modular), which loads a quantized transformer from one repository and the remaining components from another. See [Modular repository](#modular-repository) for more details on the format and shared caching. ```py from diffusers import ModularPipeline, ComponentsManager @@ -401,15 +401,16 @@ A repository is required if the pipeline blocks use *pretrained components*. The - `library` and `class` shows which library the component was loaded from and its class. If `null`, the component hasn't been loaded yet. - `loading_specs_dict` contains the information required to load the component such as the repository and subfolder it is loaded from. -The key advantage of a modular repository is that components can be loaded from different repositories. For example, [diffusers/flux2-bnb-4bit-modular](https://huggingface.co/diffusers/flux2-bnb-4bit-modular) loads a quantized transformer from `diffusers/FLUX.2-dev-bnb-4bit` while loading the remaining components from `black-forest-labs/FLUX.2-dev`. +Prefer a self-contained modular repository with its components stored alongside `modular_model_index.json`. Avoid cross-repository references solely to save download traffic or disk space: with `huggingface_hub>=1.32.0`, identical Xet-backed files can share a cached payload across repositories. See [Save a self-contained copy](#save-a-self-contained-copy) for the cache requirements and limitations. Use external references only when you intentionally want to load components hosted elsewhere. -To convert a regular diffusers repository into a modular one, create the pipeline using the regular repository, and then push to the Hub. The saved repository will contain a `modular_model_index.json` with all the loading specifications. +To convert a regular diffusers repository into a self-contained modular one, create the pipeline using the regular repository, load its components, and then push to the Hub. The saved repository will contain the components and a `modular_model_index.json` with all the loading specifications. ```py from diffusers import ModularPipeline # load from a regular repo pipeline = ModularPipeline.from_pretrained("stabilityai/stable-diffusion-xl-base-1.0") +pipeline.load_components() # push as a modular repository pipeline.save_pretrained("local/path", repo_id="my-username/sdxl-modular", push_to_hub=True) @@ -435,7 +436,7 @@ Shared caching is best-effort. Setting `HF_HUB_DISABLE_SHARED_BLOBS=1` still sup #### Update an existing modular index -Migration is optional: references to the original repository already reuse its cached files. Update a reference if it was only used to avoid duplicate downloads and you want that component to load from the modular repository instead. +Existing references to the original repository continue to work. If a reference was only used to avoid duplicate downloads, prefer updating it to load from the modular repository once the component files are available there. First, check that the modular repository contains the same component configuration and all required weight files, including the weight index and every shard for a sharded checkpoint. Matching Xet hashes determine which weight files can reuse the shared cache. Keep references to components that are absent or intentionally loaded from another checkpoint. @@ -461,7 +462,7 @@ Before publishing the updated index, load it with `ModularPipeline.from_pretrain ### Keep references to existing components -Load only what's new (or nothing at all). Only loaded components are saved; everything else stays a pointer to its original repository. Use this mode when you want to replace one component while continuing to load the others from their original repository. For example, save a custom transformer while the remaining components continue to load from the base repository. +Use this mode only when you intentionally want components to remain hosted in other repositories. Only loaded components are saved; everything else keeps a reference to its original repository. For example, save a custom transformer while the remaining components continue to load from the base repository. For new repositories, prefer [saving all components together](#save-a-self-contained-copy) and relying on shared caching for identical files. ```py pipe = ModularPipeline.from_pretrained("black-forest-labs/FLUX.2-dev") From a0fa674845015e6ccf24d9617076703717a01405 Mon Sep 17 00:00:00 2001 From: Sayak Paul Date: Tue, 20 Oct 2026 10:43:50 +0530 Subject: [PATCH 2/3] Apply batched suggestions from code review Co-authored-by: YiYi Xu --- docs/source/en/modular_diffusers/modular_pipeline.md | 5 ++--- 1 file changed, 2 insertions(+), 3 deletions(-) diff --git a/docs/source/en/modular_diffusers/modular_pipeline.md b/docs/source/en/modular_diffusers/modular_pipeline.md index 002d9155ba21..71ed315c5b52 100644 --- a/docs/source/en/modular_diffusers/modular_pipeline.md +++ b/docs/source/en/modular_diffusers/modular_pipeline.md @@ -212,7 +212,8 @@ pipeline = ModularPipeline.from_pretrained( ) ``` -**A modular repository.** These repositories contain a `modular_model_index.json` that specifies where to load each component from. For new repositories, prefer storing the components in the modular repository itself. Cross-repository references are supported when components are intentionally hosted elsewhere, as in [diffusers/flux2-bnb-4bit-modular](https://huggingface.co/diffusers/flux2-bnb-4bit-modular), which loads a quantized transformer from one repository and the remaining components from another. See [Modular repository](#modular-repository) for more details on the format and shared caching. +**A modular repository.** These repositories contain a `modular_model_index.json` that specifies the class of each component and where to load it from, with the components stored alongside it. See [Modular repository](#modular-repository) for how to create one. + ```py from diffusers import ModularPipeline, ComponentsManager @@ -401,9 +402,7 @@ A repository is required if the pipeline blocks use *pretrained components*. The - `library` and `class` shows which library the component was loaded from and its class. If `null`, the component hasn't been loaded yet. - `loading_specs_dict` contains the information required to load the component such as the repository and subfolder it is loaded from. -Prefer a self-contained modular repository with its components stored alongside `modular_model_index.json`. Avoid cross-repository references solely to save download traffic or disk space: with `huggingface_hub>=1.32.0`, identical Xet-backed files can share a cached payload across repositories. See [Save a self-contained copy](#save-a-self-contained-copy) for the cache requirements and limitations. Use external references only when you intentionally want to load components hosted elsewhere. -To convert a regular diffusers repository into a self-contained modular one, create the pipeline using the regular repository, load its components, and then push to the Hub. The saved repository will contain the components and a `modular_model_index.json` with all the loading specifications. ```py from diffusers import ModularPipeline From 5092a1d2b8a4217fae781e48ca4b82c19c51b752 Mon Sep 17 00:00:00 2001 From: sayakpaul Date: Tue, 20 Oct 2026 11:05:28 +0530 Subject: [PATCH 3/3] add separate section on referencing components in other repos. --- .../en/modular_diffusers/modular_pipeline.md | 14 +++++++++++--- 1 file changed, 11 insertions(+), 3 deletions(-) diff --git a/docs/source/en/modular_diffusers/modular_pipeline.md b/docs/source/en/modular_diffusers/modular_pipeline.md index 71ed315c5b52..9a9d2353d83f 100644 --- a/docs/source/en/modular_diffusers/modular_pipeline.md +++ b/docs/source/en/modular_diffusers/modular_pipeline.md @@ -212,15 +212,15 @@ pipeline = ModularPipeline.from_pretrained( ) ``` -**A modular repository.** These repositories contain a `modular_model_index.json` that specifies the class of each component and where to load it from, with the components stored alongside it. See [Modular repository](#modular-repository) for how to create one. - +**A modular repository.** These repositories contain a `modular_model_index.json` that specifies the class of each component and where to load it from, with the components stored alongside it. See [Modular repository](#modular-repository) for how to create one. + ```py from diffusers import ModularPipeline, ComponentsManager components = ComponentsManager() pipeline = ModularPipeline.from_pretrained( - "diffusers/flux2-bnb-4bit-modular", components_manager=components + "MiniMaxAI/MiniMax-H3", components_manager=components ) ``` @@ -495,3 +495,11 @@ The `config.json` file contains an `auto_map` key that tells [`ModularPipeline`] ``` Load custom code repositories with `trust_remote_code=True` as shown in [from_pretrained](#frompretrained). See [Custom blocks](./custom_blocks) for how to create and share your own. + +### Referencing components in other repositories + +A component's loading specification in `modular_model_index.json` can point to a different repository. For example, [diffusers/flux2-bnb-4bit-modular](https://huggingface.co/diffusers/flux2-bnb-4bit-modular) loads its quantized transformer from `diffusers/FLUX.2-dev-bnb-4bit` and the remaining components from `black-forest-labs/FLUX.2-dev`. + +We strongly prefer self-contained repositories: keeping all components together makes a pipeline easier to download, share, and use offline without depending on other repositories. Use cross-repository references only when you intentionally want a component hosted elsewhere. + +With `huggingface_hub>=1.32.0`, identical Xet-backed files can share one cached payload across repositories through symlinks, avoiding duplicate downloads and disk usage. Cross-repository references aren't needed for this. See [Save a self-contained copy](#save-a-self-contained-copy) for the shared cache requirements and limitations.