custom-nodes/backend/lists

[giscus[bot]]

custom-nodes/backend/lists

https://docs.comfy.org/custom-nodes/backend/lists

[set-soft]

I might be confused, but when reading it I got the wrong idea. As it says "An example of this might be processing a series of images one at a time to avoid running out of VRAM" I though the graph will be processed N times. But looking at the actual behavior each node is processed N times and the graph just once. I understand it might solve VRAM issues, but not RAM issues. I want to process a hundreds or thousands of images, sure they don't fit in VRAM, but the same applies to RAM.
It should be clear this doesn't solve it, and looks like the problem doesn't have an efficient solution, in particular since V3 spec is asking for stateless nodes. So the only state might be the disk ... this implies reading the directories over and over.

[geroldmeisinger]

check cache parameters, maybe they can help for your use-case

  --cache-classic       Use the old style (aggressive) caching.
  --cache-lru CACHE_LRU
                        Use LRU caching with a maximum of N node results
                        cached. May use more RAM/VRAM.
  --cache-none          Reduced RAM/VRAM usage at the expense of executing
                        every node for each run.
  --cache-ram [CACHE_RAM]
                        Use RAM pressure caching with the specified headroom
                        threshold. If available RAM drops below the threhold
                        the cache remove large items to free RAM. Default 4GB

Btw there are certain custom nodes which allow you to clear up RAM during execution, and I also assume there should be special image loading custom nodes which have special RAM management. But if you deal with that amount of data I would recommend to handle the image loading in a python script and call ComfyUI via the API.

[geroldmeisinger]

I have difficulty understanding this page
(please excuse the seemingly angry tone, I'm just explaining my thoughts :) )

Internally, the Comfy server represents data flowing from one node to the next as a Python list, normally length 1, of the relevant datatype. In normal operation, when a node returns an output, each element in the output tuple is separately wrapped in a list (length 1); then when the next node is called, the data is unwrapped and passed to the main function.

why are you explaining this? please state the goal. (the first sentence of the next section makes more sense at this point).
does this have anything to do with handling lists in nodes?
do I have to use this if I want to handle lists of ints?
do I have to use this if I want to handle image batches?
what is the "main function" in this case?
when I debug into the node's run function, all the types are scalars, not lists of length=1.

You generally don’t need to worry about this, since Comfy does the wrapping and unwrapping.

why is it explained then? please state the goal.
I don't need to worry as a node user, or not worry as a node developer?

In some circumstance, multiple data instances are processed in a single workflow, in which case the internal data will be a list containing the data instances.

what are "data instances" in this case?

An example of this might be processing a series of images one at a time to avoid running out of VRAM, or handling images of different sizes.

does this mean I cannot rely on the batch length of images in my node, because comfy rebatches them as it pleases?
does this have anything to do with execution inversion? (btw: execution inversion is not explained anywhere)

By default, Comfy will process the values in the list sequentially:
if the inputs are lists of different lengths, the shorter ones are padded by repeating the last value
the main method is called once for each value in the input lists
the outputs are lists, each of which is the same length as the longest input

I made two nodes "input: image0, image1, int", one time with and one time without INPUT_IS_LIST and found this not to be the case. if I hook it up with a image0 (batch_size=3) and image1 (batch_size=5), they still have batch_sizes 3 and 5 (as a single entry or a list len=1). If I use a node which constructs image lists (OUTPUT_IS_LIST), the list length are 3 and 5. no padding happens.

the padding seems useful for implementing image processing nodes which takes two images as inputs. say I want to implement a "overlay with image" node, my first image is a batch of 10 images, and my second image is just ONE logo, it would make sense to pad the shorter list (the logo in this case) to 10. does this have to do anything with this?

The relevant code can be found in the method map_node_over_list in execution.py.

if this is relevant to the explanation, please also insert the code, otherwise this should be a footnote.

However, as Comfy wraps node outputs into a list of length one, if the tuple returned by a custom node contains a list, that list will be wrapped, and treated as a single piece of data.

I'm lost.

INPUT_IS_LIST

The article seems to be cut off here

(The same text was posted here in 2025-04 #69)

[geroldmeisinger]

It's funny you mention implementing nodes, while thinking about Cartesian products I came up with an idea to build output list generators and list combiners for the long-standing problem of building XYZ-Gridplots in ComfyUI:

class OutputListsCombiner:
	@classmethod
	def INPUT_TYPES(cls):
		return {
			"required": {
			},
			"optional": {
				"list_a"	: (any, ),
				"list_b"	: (any, ),
				"list_c"	: (any, ),
				"list_d"	: (any, ),
			}
		}

	INPUT_IS_LIST 	= True
	RETURN_NAMES  	= ("unzip_a"	, "unzip_b"	, "unzip_c"	, "unzip_d"	)
	RETURN_TYPES  	= (any      	, any      	, any      	, any      	)
	OUTPUT_IS_LIST	= (True     	, True     	, True     	, True     	)
	FUNCTION      	= "compute"
	CATEGORY      	= "Utility"

	def compute(self, list_a = [], list_b = [], list_c = [], list_d = []):
		normalized	= [lst if len(lst) > 0 else [None] for lst in [list_a, list_b, list_c, list_d]]
		product   	= list(itertools.product(*normalized))
		transposed	= tuple(map(list, zip(*product)))
		return transposed

[geroldmeisinger]

outputlists-combiner - ComfyUI custom nodes to create output lists with strings and numbers, make combinations of them to help with XYZ-Gridplots

[geroldmeisinger]

@set-soft (or anyone): do you know if it's possible to treat multiple nodes as a group when processing the data sequentially? when I send a list to KSampler it processes multiple times before calling VAE Decode and Save Image. I want to force the KSampler to process them immediately to output the image while running "KSampler > VAE Decode > Save Image" sequentially together. use case: get intermediate images for image grid immediately, create grid once everything is finished. Something like a KSampler that has VAE Decode and Save Image included inside, but not as a custom node, but as a Subgraph which is set to "process together". Or a group node with a toggle: treat as sequential group.

It almost seems like Mode is meant for that: https://docs.comfy.org/development/core-concepts/nodes#mode but it's not implemented

`Error: SaveImage.save_images() got an unexpected keyword argument 'onTrigger'`

Comfy-Org/ComfyUI#704
Comfy-Org/ComfyUI#1135
Comfy-Org/ComfyUI#7443

update: turns out, one workaround is to build them with Node Expansion which makes them essentially one node.
#605 (comment)

[set-soft]

@set-soft (or anyone): do you know if it's possible to treat multiple nodes as a group when processing the data sequentially?

From what I saw in execution.py the code solves things node by node. If the node supports lists it executes it once, passing the lists (not padding). If the node doesn't support lists it executes the node as many times as the longest list. For lists that aren't as long as the longest it repeats the last element, this is what the documentation means by padding.

It almost seems like Mode is meant for that: https://docs.comfy.org/development/core-concepts/nodes#mode but it's not implemented

I don't know the original intend, but doesn't look like it was for this.

update: turns out, one workaround is to build them with Node Expansion which makes them essentially one node. #605 (comment)

Interesting, but really rigid. This is the same as writing a custom node that instantiates the needed nodes and executes them. The only difference is that ComfyUI can handle the intermediate values caches.

In my case I must use the "Run queue" because there is no way to load a dataset like DIS-TE1 on RAM, just the tensors for the images are around 110 GiB. If we could choose to run the graph N times instead of running individual nodes N times the problem of a large dataset will go away.

[geroldmeisinger]

feature request "Treat a group of nodes as a sequential unit" Comfy-Org/ComfyUI#11131

[geroldmeisinger]

I think I figured it out now.

READ THIS IF YOU WANT TO UNDERSTAND

To follow along make a list of something and connect it to a KSampler. Make sure whatever node you use is a real OUTPUT_IS_LIST list, e.g. "ImpactPack: Make List (Any)" or "ImpactPack: Image Batch to Image List", not of type LIST(!) or something else (most custom nodes seem to use the wrong type here). Now hit run and observe that the KSampler node is executed multiple times, once for each entry. The created images are not a batch, but a list, hence why there is a small gap between them.

Two lists

Now make an additional list and connect it to another value in the same KSampler. Take moment to think about what will happen when you hit run:
a) Take one item from list 1, then iterate over all of list 2, then the second item from list 1 and iterate list 2 again etc. (i.e. all combinations, or a "Cartesian product")?
b) Take first item from list 1 AND list 2, then the second item from list 1 AND list 2 etc. (a "zip")?

Notice that last two images are the inverted one. What doesn't happen here is a cartesian product where we would expect 6 images, i.e. [(cat, example), (cat, inverted), (dog, example), (dog, inverted), (rat, example), (rat, inverted)].

Padding

Now make the two lists of different lengths. What should happen if there are no more items left in one list?
The current implementation continues to process the longer list, but uses the last item available from the shorter list (hence a "padding").

Mental model

Intuitively you can think about it as "the list node is emitting items one by one". Technically this is not correct but for most practical purposes it's good enough.

Internally, the Comfy server represents data flowing from one node to the next as a Python list, normally length 1, of the relevant datatype. You generally don’t need to worry about this, since Comfy does the wrapping and unwrapping.

What really happens if you set OUTPUT_IS_LIST=True is that the node tells the node downstream to process the items one-by-one. The downstream node will run multiple times, and when it's finished, again tells any node downstream to process items one-by-one. (I believe this is incorrect and the node should forward the results immediately). A downstream node can override this behaviour by declaring INPUT_IS_LIST=True, and thus will not execute multiple times, but instead get ALL results at once, as a python list.

Internally Comfy always uses lists and there are essentially 3 cases:

• the node outputs a single value, Comfy will wrapped it into a list of length 1 (standard case)
• the node defines a custom MyLIST type, Comfy will wrapped it into a list of length 1, hence a unit list containing a MyList (this is usually a wrong implementation)
• the node declares OUTPUT_IS_LIST=True and outputs the values as a list, Comfy passes the list through and does it's magic explained above.

Update: I developed a whole node pack around this concept if you want to know more and make use of this great feature https://github.com/geroldmeisinger/ComfyUI-outputlists-combiner

Update2: I think this explanation is important, thus I posted it again, so it doesn't get collapsed in sub.