ModularPipelineBlocks\nsubclass in a local Python file and needs to package it into a Hub-uploadable\ndirectory. Covers the workflow from a single block.py file to a published\ncustom-block repo that consumers can load via\nModularPipeline.from_pretrained(<repo>, trust_remote_code=True).A ModularPipelineBlocks subclass is a unit of pipeline logic — input/output spec plus a __call__ — that\nslots into diffusers' modular pipeline composition. Once you have one defined locally, you almost always want to\npublish it as a small Hub repo so others can from_pretrained it. diffusers-cli custom_blocks automates the\npackaging step: it parses your Python file, instantiates the chosen block class, and writes a\nsave_pretrained-style directory in your cwd that's ready to push to the Hub.
Use this skill when:
\nblock.py (or similar) file with one or more ModularPipelineBlocks subclasses.ModularPipelineBlocks.from_pretrained\nexpects.Don't use this skill for: running an existing modular pipeline (diffusers-cli run), introspecting one\n(diffusers-cli schema), or writing the block class itself — this skill packages an already-written block.
[you: write block.py] → diffusers-cli custom_blocks → [packaged dir in cwd]\n ↓\n hf upload <repo> .\n ↓\n consumers: ModularPipeline.from_pretrained(<repo>, trust_remote_code=True)\n diffusers-cli schema --model <repo> --trust-remote-code\n diffusers-cli run --model <repo> --trust-remote-code ...\nThe skill covers the middle box. The bookends (writing the block and uploading) are out of scope.
\ndiffusers-cli custom_blocks [--block_module_name <file.py>] [--block_class_name <ClassName>]\n--block_module_name <file> — Python file containing the block class. Defaults to block.py in the cwd.--block_class_name <name> — Which class in the file to package. Optional: if omitted, the CLI parses the\nfile with ast, finds every class that inherits from ModularPipelineBlocks, and uses the first one (with\nan info log naming the others). Specify explicitly when the file defines more than one block and you want a\nspecific one.<file> without executing it, walks top-level ClassDef nodes, and collects every\nclass whose bases include ModularPipelineBlocks.--block_class_name if given, else the first found. Errors with the list of available\nclasses if your name doesn't match.importlib.util.spec_from_file_location (this does execute the\nmodule — make sure your block.py is something you trust to run), instantiates the chosen class with no\nconstructor args, and calls .save_pretrained(os.getcwd()).The result is a Hub-uploadable directory laid out the way ModularPipelineBlocks.from_pretrained expects:\nyour block source, an auto_map in the config so consumers know to load it with trust_remote_code=True,\nand any artifacts save_pretrained writes for that block class.
Given a block.py like:
from diffusers.modular_pipelines import ModularPipelineBlocks, InputParam, OutputParam\n\nclass MyDenoiseBlock(ModularPipelineBlocks):\n model_name = \"my-denoise\"\n\n @property\n def inputs(self):\n return [\n InputParam(\"latents\", type_hint=\"torch.Tensor\", required=True, description=\"Noisy latents.\"),\n InputParam(\"guidance_scale\", type_hint=\"float\", default=7.5),\n ]\n\n @property\n def intermediate_outputs(self):\n return [OutputParam(\"latents\", type_hint=\"torch.Tensor\")]\n\n def __call__(self, components, state):\n # ... denoising logic ...\n return components, state\nPackage it:
\ndiffusers-cli custom_blocks --block_module_name block.py\nOutput in cwd:
\n./\n├── block.py\n├── modular_config.json # contains auto_map → MyDenoiseBlock\n└── (any state files MyDenoiseBlock.save_pretrained writes)\nUpload to the Hub:
\nhf upload my-user/my-denoise-block .\nConsumers can now use it:
\nfrom diffusers import ModularPipeline\npipe = ModularPipeline.from_pretrained(\"my-user/my-denoise-block\", trust_remote_code=True)\nOr via CLI:
\ndiffusers-cli schema --model my-user/my-denoise-block --trust-remote-code\ndiffusers-cli run --model my-user/my-denoise-block --trust-remote-code \\\n --pipeline-kwargs '{\"latents\": \"...\", \"guidance_scale\": 7.5}'\nCould not parse '<file>': SyntaxError — the file isn't valid Python. Fix the syntax; the AST step runs\nbefore any execution.block_class_name could not be retrieved. Available classes from <file>: [ClassA, ClassB] — your\n--block_class_name doesn't match any ModularPipelineBlocks subclass found. Pick from the list shown.IndexError. If you hit that, double-check your class actually inherits from ModularPipelineBlocks\n(the AST scan looks for that literal base-class name; aliased imports like from diffusers import ... as MPB won't be picked up).<ClassName>() with no args. If your block needs\n__init__ parameters, refactor to take them from state/components at __call__ time instead, or\nhardcode defaults in __init__.If diffusers-cli isn't on PATH after pip install -e ., reinstall with\npip install -e . --force-reinstall --no-deps and check which diffusers-cli. If the binary is missing recent\nfeatures (e.g. unrecognized arguments: --lora), reinstall. See the\ndiffusers-cli skill for more.
diffusers-cli docs — once your block\nis uploaded, schema and run call it from the terminal without writing Python.