ComfyUI Data Lists

ComfyUI Data Lists Guide

Batch vs List

Batch: First dimension of tensor (B). Node called once. GPU efficient.

batch_images = torch.randn(4, 512, 512, 3)  # [4, H, W, C]

List: Python list of items. By default, node called for each item.

list_images = [torch.randn(1, 512, 512, 3) for _ in range(4)]

INPUT_IS_LIST

All Inputs as List

class ListProcessor(io.ComfyNode):
    INPUT_IS_LIST = True  # All inputs become lists

    @classmethod
    def execute(cls, images, strength) -> io.NodeOutput:
        # images: [img1, img2, ...]
        # strength: [1.0, 1.0, ...] (broadcast)
        results = []
        for i, img in enumerate(images):
            s = strength[i] if i < len(strength) else strength[0]
            results.append(process(img, s))
        return io.NodeOutput(results)

Partial List Input

class PartialListProcessor(io.ComfyNode):
    INPUT_IS_LIST = ("images",)  # Only images as list

    @classmethod
    def execute(cls, images, strength) -> io.NodeOutput:
        # images: list, strength: single value
        results = [process(img, strength) for img in images]
        return io.NodeOutput(results)

OUTPUT_IS_LIST

class ListOutputNode(io.ComfyNode):
    OUTPUT_IS_LIST = (True,)  # First output is list

    @classmethod
    def execute(cls, image, count) -> io.NodeOutput:
        results = [image.clone() for _ in range(count)]
        return io.NodeOutput(results)

Multiple Outputs

class MultiListOutput(io.ComfyNode):
    OUTPUT_IS_LIST = (True, False, True)  # Per-output setting
    INPUT_IS_LIST = True

    @classmethod
    def execute(cls, images) -> io.NodeOutput:
        processed = [process(img) for img in images]
        count = len(images)
        names = [f"image_{i}" for i in range(count)]
        return io.NodeOutput(processed, count, names)

Example: Rebatch Node

class ImageRebatch(io.ComfyNode):
    INPUT_IS_LIST = True
    OUTPUT_IS_LIST = (True,)

    @classmethod
    def define_schema(cls):
        return io.Schema(
            node_id="ImageRebatch",
            category="utils/batch",
            inputs=[
                io.Image.Input("images"),
                io.Int.Input("batch_size", default=2, min=1),
            ],
            outputs=[io.Image.Output(display_name="batches")],
        )

    @classmethod
    def execute(cls, images, batch_size) -> io.NodeOutput:
        bs = batch_size[0] if isinstance(batch_size, list) else batch_size
        batches = []
        for i in range(0, len(images), bs):
            batch = torch.cat(images[i:i+bs], dim=0)
            batches.append(batch)
        return io.NodeOutput(batches)

Batch vs List Comparison

Feature	Batch	List
Memory	Contiguous	Distributed
GPU Efficiency	High	Low
Variable sizes	Hard	Easy
Node calls	1	N (or 1 with INPUT_IS_LIST)

Use Batch: Same-size images, GPU optimization Use List: Variable sizes, sequential processing

Common Mistakes

# WRONG: Using list instead of tuple
OUTPUT_IS_LIST = [True]

# CORRECT: Use tuple
OUTPUT_IS_LIST = (True,)

# Handle empty lists
@classmethod
def execute(cls, items) -> io.NodeOutput:
    if not items:
        return io.NodeOutput([])
    results = [process(item) for item in items]
    return io.NodeOutput(results)