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]

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)

[set-soft]

I'm using lists now, what I found is:

• Nothing is padded, if some input is just a boolean widget you'll get a list with one element. So the first thing you must do is to flatten these inputs that aren't supposed to be lists. On the other hand you might want to manually repeat the value if the widget has some useful use where it is connected as an input and the node can take advantage of having a different value for each of the inputs that are supposed to be lists.
• Batches are completely separated from this concept. You might get a list of images where the first element is a batch of size 2 and the last is of size 1. And this is good because you then have 2 layers of grouping: batches, usually related to batch_size option of a node, useful to control how much VRAM we will take and a second layer tied to the number of elements in the list, this controls how much RAM we will take. So your nodes handling lists can have 2 parameters: list_size and batch_size. So the user can ask to load 10 batches of 2 images. Having 20 images in RAM and processing 2 of them at once in VRAM. As the number of images might be 19 having a list where the first 9 elements are batches of 2 images and the last is a batch of 1 image is the solution. No rebatch is done, YOU might want to generate an output that is a list of single images, in the previous example you might generate an output with 19 elements.
• The ComfyUI execution code dispatches the lists to the next node ready to process. For this it can execute the same node many times until all the inputs are consumed. Here is where the attribute that says a node takes lists is very important. This is because these nodes will be called just once, with all the collected lists at its inputs, instead of one time for each element in the input.

What I'm trying to implement is a group of nodes to evaluate models, so I have to process hundreds of images, there is no way to load them all at once. The nodes have to deal with 3 layers of storage: DISK, RAM and VRAM. This complicates things a little bit farther. But the RAM + VRAM part seems to be quite well solved using lists.