ComfyUI-ImageBatchCacher

ComfyUI Image Batch Cacher

A tiny ComfyUI custom node pack for disk-backed raw IMAGE batch checkpoints in multistage workflows.

Install only one copy of this node pack. The recommended folder name is ComfyUI-ImageBatchCacher.

Node

Image Batch Cacher

Image Batch Cacher is a lazy cache gate for expensive decoded image/video batches.

Inputs:

• signal: any type. Passed through only when the cache is missing.
• images: lazy IMAGE input. Evaluated only when the cache is missing, or when refresh/save modes require it.
• depends_on_cache: optional IMAGE_CACHE_REF. Use this for derived caches, such as interpolated frames derived from sampler frames. If the dependency cache is deleted or rewritten, this cache is treated as stale and regenerated.

Outputs:

• signal: the input signal on cache miss; an execution blocker on cache hit.
• images: cached images on cache hit; input images on cache miss.
• cache_ref: a lightweight cache reference output kept for compatibility. Do not feed it back into a gate upstream of the same branch on ComfyUI versions that validate raw links as graph dependencies.

Default behavior:

cache exists:
signal -> blocked
images -> loaded from disk

cache missing:
signal -> passed through
images -> upstream branch is evaluated, saved, and passed through

The cache is stored as a .safetensors file containing one raw ComfyUI image tensor:

image_tensor: [B, H, W, C]

By default, it saves as float16 to cut video cache size in half versus float32, and loads back as float32 in the usual ComfyUI IMAGE range of 0.0..1.0.

Modes

• load_or_save: load cached images if present; otherwise evaluate, save, and pass through the image input.
• refresh: always evaluate the image input and overwrite the cache.
• save_only: always evaluate and save the image input, then pass it through.
• load_only: load only from disk, raising an error if the cache is missing.

Image Cache Miss Gate

Image Cache Miss Gate checks the same cache_dir and cache_name as a matching Image Batch Cacher and passes signal only when that file is missing or stale. When the cache exists and its optional dependency still matches, it returns a silent execution blocker.

Use it before an expensive branch when you want extra protection against accidental direct links into that branch:

seed -> Image Cache Miss Gate signal -> sampler noise_seed
Image Cache Miss Gate cache_name/cache_dir match Image Batch Cacher cache_name/cache_dir
sampler frames -> Image Batch Cacher images -> downstream

The gate intentionally uses its own cache settings instead of a cache_ref wire. A visual link from the cacher back into a gate before the same expensive branch can be treated as a real dependency by ComfyUI validation and create a graph cycle.

For derived caches, connect the upstream cacher's cache_ref output to the downstream gate and cacher depends_on_cache inputs. This is safe when the connection points downstream, for example:

Sampler Frames cache_ref -> Interpolated Images gate depends_on_cache
Sampler Frames cache_ref -> Interpolated Images cacher depends_on_cache

This makes an existing interpolation cache go stale if the sampler-frame cache is deleted or regenerated.

Cache Path

The cache is stored under ComfyUI's output directory by default:

output/image_cache/<cache_name>.images.safetensors

cache_dir and cache_name may include relative subfolders, but absolute paths and .. are rejected.

Cache Controls

The node UI shows cache state for the current cache_dir and cache_name:

• Delete This Cache (...) when the file exists.
• No Cache To Delete when the file is missing.

Each cacher node also has a small refresh button that refreshes all cache statuses in the open workflow, plus Delete All Caches. Delete All Caches asks for confirmation, then deletes the deduplicated cache files referenced by Image Batch Cacher nodes in the currently open workflow.

Cache status is refreshed when a workflow opens, when cache path widgets change, and immediately after a cache file is saved or deleted.

Important Graph Note

Do not wire the node's signal output back into the same branch that produces the node's images input. That creates a graph cycle.

The cache skip itself is handled by ComfyUI lazy evaluation: when the cache exists, the node does not request the images input, so the upstream image-producing branch is not evaluated.

Use the signal output for downstream or side-effect work that should only happen on a cache miss.

Installation

Copy this folder into:

ComfyUI/custom_nodes/ComfyUI-ImageBatchCacher

Then restart ComfyUI. The node appears under:

Flow/Execution