Reference Images Batch (internal)

Here's a node you will almost certainly never add, and might still need to understand: Reference Images Batch (internal). The pack's own class docstring says it's "added at queue time for the Reference Prompt's 'images' output; never on the canvas." The DEPRECATED = True flag keeps it out of the node search for the same reason. It exists because some models want their references as one batch instead of numbered inputs, and turning several differently-shaped images into one batch requires a decision about what to do with the shapes.

That decision is the mode setting, and it's the reason to know this node exists. When Nano Banana Pro returns reference images with black bars, or when your subject's head is clipped in shot two but fine in shot one, this is the code doing it.

Why a batch node at all

Newer partner nodes expose growing inputs - image_1, image_2, … - that the Reference Prompt can fill directly, no wires. Older ones (Nano Banana Pro, Nano Banana) accept a single images batch. The pack supports both: for batch-input models you connect the Reference Prompt's images output to the model's images input, and at queue time the frontend slots this node in to build that batch from your tagged files. Every tagged image, in the order shown under the text, becomes one IMAGE tensor.

If you've exported an API workflow from such a graph, you've seen it: a ReferenceImagesBatch entry with a mode and an image_1…image_N per tagged file. Older exports may call it LibraryImageBatch, the same class under the pack's pre-0.1.2 id.

Inputs and outputs

• mode - required enum, three choices, default pad:
  • pad - fit each image inside the target size and fill the rest with black. Nothing is cropped. This is the default, and it's the right one for reference work: the model can still see the whole reference.
  • crop - scale to fill the target size and cut what sticks out. ComfyUI's Batch Images behaviour. Compact, and it eats edges.
  • stretch - ignore aspect ratio and squash/stretch to the target. Fast and wrong-looking, unless the model re-renders everything.
• image_1 … image_64 - up to 64 optional IMAGE inputs. They're consumed in numeric order, and a multi-frame input contributes all of its frames in sequence, so 64 slots can hold far more than 64 pictures.
• images - the stacked batch.

The target size always comes from the first image. That's the rule that makes input order a real setting: whatever you tag first defines the frame everything else is fitted into. Resizing is Lanczos. If the inputs disagree on channel count, the batch is trimmed to the smallest count - which is how an RGBA reference quietly becomes RGB here. Masks are not carried through; the node outputs IMAGE only, so if you need alpha downstream, take it from a Reference Image node before this point in the chain.

Do you ever want to add it manually?

Rarely. For hand-built batches ComfyUI's core Batch Images does the same job with a visible UI and no archaeology. This node's value is that it makes the images output work, and that its mode is where a surprising amount of "why does my reference look squashed" gets resolved.

If you do want it - say you're rebuilding an old graph by hand - it won't appear in the node search, so copy it from a saved workflow or an API export. Both ReferenceImagesBatch and the older LibraryImageBatch id still work.

Install

cd ComfyUI/custom_nodes
git clone https://github.com/PixelMonkey77/comfyui-reference-library

Restart ComfyUI, or install the same URL via ComfyUI Manager (Install via Git URL). Zero pip dependencies, zero model files.

And again, because it's the number one reason the pack appears broken: Settings → Comfy → Nodes 2.0 → Modern Node Design (Nodes 2.0) is required. The queue-time wiring that inserts this node lives in the frontend.

Common issues

Reference images with black bars. That's pad. It fits rather than fills, and the bars are the price of not cropping your reference. Reorder so a wide image is first, or switch to crop and accept the cut.

Output looks squashed or fat. You're on stretch.

The queue refuses your run entirely. If you wired a Reference Prompt's text into a batch-input model but forgot the images wire, the pack refuses rather than sending tags with no files attached. Connect both: text → prompt, images → images.

Padding is happening but you'd rather control the resize. Skip the images output and wire the Reference Prompt's individual @name outputs through your own resize, crop and batch nodes. That's the documented escape hatch, and it's the right one when a batch's fit-to-first-image rule doesn't suit you.