🧩 Image Batch Unpack (4-slot):
Archived source: The original repository xuxiao305/comfyui-imagebatchutils is unavailable. This page documents the preserved implementation at commit 54ddbf7505d5. It is a historical source snapshot, not a claim that the original repository is maintained or currently installable.
ImageBatchUnpack separates an image batch into individual images so you can send each one through a different part of a ComfyUI workflow. It takes images in their existing order and preserves each image’s original width and height, without resizing or padding them. It provides four fixed positions; positions without an available image receive tiny placeholders. The class does not declare RETURN_NAMES: all four ComfyUI sockets display the type label IMAGE, and image_1 through image_4 are positional aliases used only in this documentation, not custom socket names.
🧩 Image Batch Unpack (4-slot) Input Parameters:
images
The required IMAGE input supplies the images to separate. You can connect a batch, or a list-producing image node: because INPUT_IS_LIST is enabled, each incoming list item can itself contain multiple images. The node takes images from each item in sequence and assigns the first four individual images to its four positions. Their original dimensions are preserved. There is no declared default, minimum, maximum, or selectable option for this input; it must receive image data from a connected node.
🧩 Image Batch Unpack (4-slot) Output Parameters:
image_1
The first IMAGE output contains the first available image as an individual, single-image tensor, ready for its own downstream path. If no image is available, it contains a tiny 1×1, three-channel, zero-filled placeholder instead. image_1 is a documentation-only positional alias; the socket’s ComfyUI label is IMAGE, not a custom RETURN_NAMES label.
image_2
The second IMAGE output contains the second available image, preserving its original dimensions even when they differ from the first image’s. If fewer than two images are available, this position contains a tiny 1×1, three-channel, zero-filled placeholder. image_2 is a documentation-only positional alias; the socket’s ComfyUI label is IMAGE.
image_3
The third IMAGE output contains the third available image at its original size, allowing you to process it independently. If fewer than three images are available, this position contains a tiny 1×1, three-channel, zero-filled placeholder. image_3 is a documentation-only positional alias; the socket’s ComfyUI label is IMAGE.
image_4
The fourth IMAGE output contains the fourth available image at its original size. If fewer than four images are available, this position contains a tiny 1×1, three-channel, zero-filled placeholder. Images after the fourth are not returned by this node. image_4 is a documentation-only positional alias; the socket’s ComfyUI label is IMAGE.
🧩 Image Batch Unpack (4-slot) Usage Tips:
- Connect each position you need to a separate processing path when you want different edits or previews for images from the same batch.
- Supply at least four images when all four positions must contain real images. Check your upstream batch size if a downstream path unexpectedly receives a 1×1 placeholder.
- Keep batches to four images or fewer when every image must be available from this node. For larger or variable-size batches, consider
ImageBatchUnpackDynamic, which returns a list instead of four fixed positions. - You do not need to resize differently sized images before unpacking solely for this node: it preserves each image’s original spatial size. Check whether downstream nodes can accept those differing sizes.
- There are no adjustable performance settings on this node. Supplying only the images needed for your four paths avoids processing upstream images that this node will not return.
🧩 Image Batch Unpack (4-slot) Common Errors and Solutions:
Required input is not connected
- Explanation: ComfyUI may report a missing required
imagesinput during workflow validation. This node cannot unpack images until it receives anIMAGEconnection. - Solution: Connect an image-producing node to
imagesand run the workflow again.
AttributeError: 'NoneType' object has no attribute 'shape'
- Explanation: This can occur if an upstream source passes
Noneinstead of an image tensor. The unpacking code expects to read the batch size from each supplied tensor. - Solution: Check the node feeding
imagesand confirm that it produces valid image data for this execution.
IndexError: tuple index out of range
- Explanation: This can occur if an upstream source supplies a value without the expected batch dimension. The node expects image tensors arranged as batches, including a single-image batch.
- Solution: Use an upstream node that produces a valid ComfyUI
IMAGEbatch rather than an unbatched or otherwise malformed value.
An output is a 1×1 image
- Explanation: This is expected behavior, not an error message. When fewer images are available than output positions, each unused position receives a tiny zero-filled placeholder.
- Solution: Increase the upstream image count if that position needs a real image, or leave unused positions unconnected.
Images after the fourth are missing
- Explanation: This is a fixed four-position node. It takes the first four individual images and does not return any later ones; it does not raise an error for the extras.
- Solution: Limit the supplied batch to the four images you need, or use
ImageBatchUnpackDynamicwhen you need to retain every image.
