Variable Image Loader (SBTools)

Most ComfyUI image loaders are one-file-per-node affairs. If you want to run a batch of reference images, you either wire up a row of Load Image nodes or wrestle with a batch loader that doesn't behave. Variable Image Loader does what you actually want: it points at a folder, globs the files, and hands them to you one at a time - sequentially by index or randomly by seed - with a plain IMAGE output you can plug anywhere.

It pulls double duty in this pack. On its own it's a solid standalone folder loader (the README shows it being used just for sequential image processing, no variables involved). Wire a Variable Folder's var_list into it and it becomes the execution half of the conditional-image system - the folder mapping takes over and images switch based on your variable context. One node, two personalities.

The inputs that matter

• folder_path - absolute or relative path to the folder. Remember: when a Variable Folder is connected, this is ignored and the Folder's mapping wins.
• pattern - glob pattern. Default *; use *.png to filter, **/* (with subfolders enabled) for recursion.
• index - which image in sequential mode. Loops automatically, so you can just increment a Primitive node and run the batch.
• randomize / seed - switch to random selection; seed makes it reproducible.
• include_subfolders, include_extension, fill_background / background_color - optional controls for recursion, filename output, and transparency handling.

The quality-of-life details are where this node earns its keep. Files sort naturally (like Windows Explorer), so file10 sorts after file9 instead of after file1. Transparency is preserved by default (RGBA stays RGBA), with an opt-in fill_background to flatten to a hex color. Multibyte characters in paths and filenames work, which matters more than you'd think for non-English filenames.

Outputs

Four of them: IMAGE (the loaded image - the one you actually use), VAR_LIST (variable data, for Combiner/Builder integration), TOTAL_IMAGES (count, handy for loop logic), and FILENAME (current filename, extension optional).

How it fits the bigger picture

Two typical wiring patterns:

Standalone folder processing:

Variable Image Loader (folder: refs/, pattern: *.png)
  ├─ image → [any image node]
  └─ index ← Primitive (increment)

Conditional reference workflow:

Variable Prompt (GENDER) → Variable Folder → Variable Image Loader → Variable Builder

In the second pattern the Loader applies the Variable Folder's mapping, and its own settings (randomize, seed, fill_background, etc.) apply on top. Each loaded image also flows into the Builder as an image variable, where it slots into IMAGE1–IMAGE4 alongside the generated prompt.

Installing it

Standard pack install. ComfyUI Manager → search "ComfyUI-SBTools" → Install, or:

cd ComfyUI/custom_nodes
git clone https://github.com/Amatsukast/ComfyUI-SBTools.git
cd ComfyUI-SBTools
pip install -r requirements.txt

Restart ComfyUI. No model downloads.

Troubleshooting

• folder_path is being ignored - a Variable Folder is connected upstream. That's by design; disconnect it to get the manual path back.
• Subfolders not found - include_subfolders must be on and your pattern needs **/ (e.g., **/*.png).
• Wrong order in a batch - you're sorting alphabetically somewhere or expecting the loader to respect a different order; natural sort is built in, so file1, file2, …, file10 is the expected behavior.
• Transparency lost - that's fill_background being on. Turn it off to keep RGBA.

For anything involving "run these 50 reference images through the same workflow," this is the node that replaces fifty Load Image nodes with one folder path.