Shuffle Pairs of Image-Text

Here's the scenario: you've got a list of images and a matching list of captions, and you want to shuffle them. If you reach for a plain image-shuffle node, you just destroyed your dataset - the images are now in a new order but the captions still point at the old one, and every pair from position 2 onward is garbage. Shuffle Pairs of Image-Text exists precisely so you don't do that.

It shuffles both lists together, using the same permutation, so every image keeps its caption. Image 5's caption follows image 5 wherever it lands. That one property is the whole reason the node exists.

Where you'll use it

This node is squarely aimed at dataset work. The experimental dataset family it belongs to includes "Load Image-Text (from Folder)" - which reads image+caption pairs from a directory - and this node is the shuffle step that pairs with it. Typical flow: load pairs → shuffle pairs → sample a subset → do something with the data (preview, caption check, or just feeding a consistent pair list into some other process).

It's also handy for training-side workflows in the graph, where you often want the order of training pairs randomized between passes so the model isn't memorizing the order it was fed. Captioning quality is the thing that actually moves training results, but ordering matters more than people admit, and this is the node that handles order without touching pairings.

How it works

The mechanism couldn't be more symmetric: compute one random permutation of the list indices, then apply it to both lists. Same seed, same permutation, both lists - that's the whole implementation. There's no magic keeping pairs aligned; it's that both sides are indexed and reordered identically.

The inputs and outputs, straight from the schema:

• images - the list of images to shuffle.
• texts - the list of texts to shuffle. This is a forced list input - it expects the caption list wired in, not typed text.
• seed (default 0, 0 to 2^64−1) - the random seed. Fixed seed = same shuffle every run; vary it for a fresh order.
• Outputs: images (the shuffled list) and texts (the shuffled list, in the same new order).

Wire the two outputs into whatever needs the pair, and trust that positions still line up.

Gotchas

• Both lists must be the same length. The permutation indexes into both, so a length mismatch throws an error (or worse, silently drops the tail on one side). If your caption file has fewer lines than your image folder, fix the dataset before shuffling, not after.
• Fixed seed is deterministic. Same seed = same order every run, which is what you want for debugging and reproducibility. If you expected a fresh random shuffle on every queue, you have to vary the seed.
• It's marked experimental. This node carries the experimental flag in core - it works, but its exact behavior is more likely to shift between ComfyUI versions than the classics. Pin your ComfyUI version if you build a production workflow around it.

The contrast that keeps people sane

If you only have images and no captions, use plain Shuffle Images List (ShuffleDataset) - same seed logic, no texts to worry about. If you have pairs, use this one. The mistake people make is using the image-only shuffle on paired data and only noticing the mismatch when the workflow produces nonsense halfway down the list. Don't be that person; pick the pair-aware node.

Ships with ComfyUI core - no install, no models. One permutation, applied twice, and your dataset stays coherent.