diffusers/pr_14159/en/api/modular_diffusers/pipeline_blocks.md

Pipeline blocks

ModularPipelineBlocks[[diffusers.ModularPipelineBlocks]]

diffusers.ModularPipelineBlocks[[diffusers.ModularPipelineBlocks]]

diffusers.ModularPipelineBlocks()

Source

Base class for all Pipeline Blocks: ConditionalPipelineBlocks, AutoPipelineBlocks, SequentialPipelineBlocks, LoopSequentialPipelineBlocks

ModularPipelineBlocks provides method to load and save the definition of pipeline blocks.

get_block_state[[diffusers.ModularPipelineBlocks.get_block_state]]

get_block_state(state: PipelineState)

Source

Get all inputs and intermediates in one dictionary

get_execution_blocks[[diffusers.ModularPipelineBlocks.get_execution_blocks]]

get_execution_blocks(**kwargs)

Source

Parameters:

• **kwargs : Input names and values. Only trigger inputs affect block selection.

Get the block(s) that would execute given the inputs. Must be implemented by subclasses that support conditional block selection.

get_workflow[[diffusers.ModularPipelineBlocks.get_workflow]]

get_workflow(workflow_name: str)

Source

Parameters:

workflow_name : Name of the workflow to retrieve.

Get the execution blocks for a specific workflow. Must be implemented by subclasses that define _workflow_map.

init_pipeline[[diffusers.ModularPipelineBlocks.init_pipeline]]

init_pipeline(pretrained_model_name_or_path: str | os.PathLike | None = None, components_manager: diffusers.modular_pipelines.components_manager.ComponentsManager | None = None, collection: str | None = None)

Source

create a ModularPipeline, optionally accept pretrained_model_name_or_path to load from hub.

stream[[diffusers.ModularPipelineBlocks.stream]]

stream(components, state: PipelineState)

Source

Run the block as a generator that yields a StreamEvent after every iteration of every loop block it contains, and returns (components, state) when done. A block with no loops runs to completion and yields nothing; composite blocks re-yield their sub-blocks' events with the sub-block name prepended to event.path.

SequentialPipelineBlocks[[diffusers.SequentialPipelineBlocks]]

diffusers.SequentialPipelineBlocks[[diffusers.SequentialPipelineBlocks]]

diffusers.SequentialPipelineBlocks()

Source

Parameters:

block_classes : list of block classes to be used

block_names : list of prefixes for each block

A Pipeline Blocks that combines multiple pipeline block classes into one. When called, it will call each block in sequence.

This class inherits from ModularPipelineBlocks. Check the superclass documentation for the generic methods the library implements for all the pipeline blocks (such as loading or saving etc.)

from_blocks_dict[[diffusers.SequentialPipelineBlocks.from_blocks_dict]]

from_blocks_dict(blocks_dict: dict, description: str | None = None)

Source

Parameters:

blocks_dict : Dictionary mapping block names to block classes or instances

Returns:

A new SequentialPipelineBlocks instance

Creates a SequentialPipelineBlocks instance from a dictionary of blocks.

get_execution_blocks[[diffusers.SequentialPipelineBlocks.get_execution_blocks]]

get_execution_blocks(**kwargs)

Source

Parameters:

• **kwargs : Input names and values. Only trigger inputs affect block selection.

Returns:

SequentialPipelineBlocks containing only the blocks that would execute

Get the blocks that would execute given the specified inputs.

As the traversal walks through sequential blocks, intermediate outputs from resolved blocks are added to the active inputs. This means conditional blocks that depend on intermediates (e.g., "run img2img if image_latents is present") will resolve correctly, as long as the condition is based on presence/absence (None or not None), not on the actual value.

ModularLoopPipelineBlocks[[diffusers.ModularLoopPipelineBlocks]]

diffusers.ModularLoopPipelineBlocks[[diffusers.ModularLoopPipelineBlocks]]

diffusers.ModularLoopPipelineBlocks()

Source

Base class for leaf blocks that run inside an IterativePipelineBlocks loop.

The only difference from ModularPipelineBlocks is the __call__ contract: in addition to (components, state), the block receives the enclosing loop's variables as keyword call arguments — its signature names the loop variables it uses and declares **kwargs for any it ignores (e.g. def __call__(self, components, state, t, **kwargs); naming all of them without **kwargs works too). The loop validates this at construction: a named parameter that is not a loop variable, or a missing loop variable without a **kwargs catch-all, raises.

> This is an experimental feature and is likely to change in the future.

IterativePipelineBlocks[[diffusers.IterativePipelineBlocks]]

diffusers.IterativePipelineBlocks[[diffusers.IterativePipelineBlocks]]

diffusers.IterativePipelineBlocks()

Source

Parameters:

block_classes : list of block classes to be used (same as SequentialPipelineBlocks)

block_names : list of names for each block (same as SequentialPipelineBlocks)

A pipeline blocks that runs its sub-blocks multiple times. Subclasses declare their loop-variable names in loop_variables and implement __call__ with their loop logic — the same way leaf blocks implement __call__

around get_block_state — calling loop_step once per iteration with the loop variables:

@property
def loop_variables(self):
    return ["i", "t"]

@torch.no_grad()
def __call__(self, components, state):
    block_state = self.get_block_state(state)
    for i, t in enumerate(block_state.timesteps):
        components, state = self.loop_step(components, state, i=i, t=t)
    return components, state

Unlike LoopSequentialPipelineBlocks, sub-blocks operate on the full PipelineState with the regular get_block_state/set_block_state behavior, so an IterativePipelineBlocks can itself be a sub-block of another one — loops can be nested and composed freely. Sub-blocks must be ModularLoopPipelineBlocks (loop steps) or nested IterativePipelineBlocks, which is validated at construction.

Loop variables are passed to sub-blocks as keyword call arguments: a sub-block's __call__ names the loop variables it uses after (components, state) and declares **kwargs for any it ignores (naming all of them and omitting **kwargs is fine too). This is validated at construction: a named parameter that is not a loop variable, or a missing loop variable without a **kwargs catch-all, raises. A nested loop accepts the outer loop's variables in its own hand-written __call__ (ignoring or forwarding them) and passes its own loop_variables to its own

sub-blocks:

class InnerDenoiseLoop(IterativePipelineBlocks):
    @property
    def loop_variables(self):
        return ["i", "t"]  # what it passes to ITS sub-blocks

    @torch.no_grad()
    def __call__(self, components, state, k):  # accepts the OUTER chunk loop's variable
        block_state = self.get_block_state(state)
        for i, t in enumerate(block_state.timesteps):
            components, state = self.loop_step(components, state, i=i, t=t)
        return components, state

Sub-block outputs are written to the pipeline state as usual and persist after the loop. The loop logic's own inputs (e.g. timesteps) and outputs are declared in loop_inputs / loop_intermediate_outputs: they join the sub-blocks' in the aggregated inputs / intermediate_outputs, and they are what get_block_state / set_block_state read and write for the loop block itself — sub-block values live in the pipeline state, not in the loop's block state. A component used by the loop logic itself (e.g. the scheduler) is added by overriding expected_components.

Streaming is opt-in: to let pipe.stream(...) hand back the live PipelineState after every iteration, also implement stream — the same loop, written as a generator over stream_step (which runs one iteration like

loop_step and additionally yields a StreamEvent for it, after any events of a nested loop):

def stream(self, components, state):
    block_state = self.get_block_state(state)
    for i, t in enumerate(block_state.timesteps):
        components, state = yield from self.stream_step(components, state, i=i, t=t)
    return components, state

A nested loop's stream takes the outer loop's variables exactly like its __call__ does.

> This is an experimental feature and is likely to change in the future.

get_block_state[[diffusers.IterativePipelineBlocks.get_block_state]]

get_block_state(state: PipelineState)

Source

The loop logic's own inputs (loop_inputs); sub-block values are read from the pipeline state.

loop_step[[diffusers.IterativePipelineBlocks.loop_step]]

loop_step(components, state: PipelineState, **loop_kwargs)

Source

Run all sub-blocks once over the pipeline state (one loop iteration), passing the loop variables.

set_block_state[[diffusers.IterativePipelineBlocks.set_block_state]]

set_block_state(state: PipelineState, block_state: BlockState)

Source

Write the loop logic's own outputs (loop_intermediate_outputs) and modified inputs back to the state.

stream_step[[diffusers.IterativePipelineBlocks.stream_step]]

stream_step(components, state: PipelineState, **loop_kwargs)

Source

The streaming counterpart of loop_step: a generator that runs all sub-blocks once, re-yields the events of any nested loop, then yields one StreamEvent for this iteration and returns (components, state). Call it with yield from inside stream.

LoopSequentialPipelineBlocks[[diffusers.LoopSequentialPipelineBlocks]]

diffusers.LoopSequentialPipelineBlocks[[diffusers.LoopSequentialPipelineBlocks]]

diffusers.LoopSequentialPipelineBlocks()

Source

Parameters:

block_classes : list of block classes to be used

block_names : list of prefixes for each block

A Pipeline blocks that combines multiple pipeline block classes into a For Loop. When called, it will call each block in sequence.

This class inherits from ModularPipelineBlocks. Check the superclass documentation for the generic methods the library implements for all the pipeline blocks (such as loading or saving etc.)

from_blocks_dict[[diffusers.LoopSequentialPipelineBlocks.from_blocks_dict]]

from_blocks_dict(blocks_dict: dict)

Source

Parameters:

blocks_dict : Dictionary mapping block names to block instances

Returns:

A new LoopSequentialPipelineBlocks instance

Creates a LoopSequentialPipelineBlocks instance from a dictionary of blocks.

AutoPipelineBlocks[[diffusers.AutoPipelineBlocks]]

diffusers.AutoPipelineBlocks[[diffusers.AutoPipelineBlocks]]

diffusers.AutoPipelineBlocks()

Source

Parameters:

block_classes : List of block classes to be used. Must have the same length as block_names and block_trigger_inputs.

block_names : List of names for each block. Must have the same length as block_classes and block_trigger_inputs.

block_trigger_inputs : List of input names where each element specifies the trigger input for the corresponding block. Use None to mark the default block.

A Pipeline Blocks that automatically selects a block to run based on the presence of trigger inputs.

This is a specialized version of ConditionalPipelineBlocks where:

• Each block has one corresponding trigger input (1:1 mapping)
• Block selection is automatic: the first block whose trigger input is present gets selected
• block_trigger_inputs must have the same length as block_names and block_classes
• Use None in block_trigger_inputs to specify the default block, i.e the block that will run if no trigger inputs are present

Example:

    class MyAutoBlock(AutoPipelineBlocks):
        block_classes = [InpaintEncoderBlock, ImageEncoderBlock, TextEncoderBlock]
        block_names = ["inpaint", "img2img", "text2img"]
        block_trigger_inputs = ["mask_image", "image", None]  # text2img is the default

With this definition:

• As long as mask_image is provided, "inpaint" block runs (regardless of image being provided or not)
• If mask_image is not provided but image is provided, "img2img" block runs
• Otherwise, "text2img" block runs (default, trigger is None)

select_block[[diffusers.AutoPipelineBlocks.select_block]]

select_block(**kwargs)

Source

Select block based on which trigger input is present (not None).

ConditionalPipelineBlocks[[diffusers.ConditionalPipelineBlocks]]

diffusers.ConditionalPipelineBlocks[[diffusers.ConditionalPipelineBlocks]]

diffusers.ConditionalPipelineBlocks()

Source

Parameters:

block_classes : List of block classes to be used. Must have the same length as block_names.

block_names : List of names for each block. Must have the same length as block_classes.

block_trigger_inputs : List of input names that select_block() uses to determine which block to run. For ConditionalPipelineBlocks, this does not need to correspond to block_names and block_classes. For AutoPipelineBlocks, this must have the same length as block_names and block_classes, where each element specifies the trigger input for the corresponding block.

default_block_name : Name of the default block to run when no trigger inputs match. If None, this block can be skipped entirely when no trigger inputs are provided.

A Pipeline Blocks that conditionally selects a block to run based on the inputs. Subclasses must implement the select_block method to define the logic for selecting the block. Currently, we only support selection logic based on the presence or absence of inputs (i.e., whether they are None or not)

This class inherits from ModularPipelineBlocks. Check the superclass documentation for the generic methods the library implements for all the pipeline blocks (such as loading or saving etc.)

get_execution_blocks[[diffusers.ConditionalPipelineBlocks.get_execution_blocks]]

get_execution_blocks(**kwargs)

Source

Parameters:

• **kwargs : Input names and values. Only trigger inputs affect block selection.

Returns: - ModularPipelineBlocks

A leaf block or resolved SequentialPipelineBlocks

• None: If this block would be skipped (no trigger matched and no default)

Get the block(s) that would execute given the inputs.

Recursively resolves nested ConditionalPipelineBlocks until reaching either:

• A leaf block (no sub_blocks, or a loop block: IterativePipelineBlocks / LoopSequentialPipelineBlocks) → returns single ModularPipelineBlocks
• A SequentialPipelineBlocks → delegates to its get_execution_blocks() which returns a SequentialPipelineBlocks containing the resolved execution blocks

select_block[[diffusers.ConditionalPipelineBlocks.select_block]]

select_block(**kwargs)

Source

Parameters:

• **kwargs : Trigger input names and their values from the state.

Returns: str | None

The name of the block to run, or None to use default/skip.

Select the block to run based on the trigger inputs. Subclasses must implement this method to define the logic for selecting the block.

Note: When trigger inputs include intermediate outputs from earlier blocks, the selection logic should only depend on the presence or absence of the input (i.e., whether it is None or not), not on its actual value. This is because get_execution_blocks() resolves conditions statically by propagating intermediate output names without their runtime values.