ComfyUI-BatchFolderTools Introduction
ComfyUI-BatchFolderTools lets you run a ComfyUI workflow over a folder of images or videos, one file at a time. Instead of selecting each file and clicking Queue Prompt repeatedly, you set a folder path and start the batch once. You can use it for tasks such as writing captions, upscaling images, applying a style, analyzing videos, or extracting frames, depending on what the rest of your workflow does.
The extension reads files directly from their existing folder. You do not need to copy them into ComfyUI’s input or cache directory. For captioning projects, it can also skip files that already have a caption, making it easier to continue after an interrupted run.
All of its nodes appear under 📂 BatchFolder in ComfyUI’s node browser.
How ComfyUI-BatchFolderTools Works
Think of your workflow as a workstation and the folder as a stack of files waiting beside it. A folder loader brings in one file, your connected nodes process it, and Queue Next starts another pass through the same workflow. In sequential mode, the loader advances to the next file on each pass. When there are no files left, the batch stops.
The loader also supplies information about the current file, including its folder path and filename. You can use those outputs elsewhere in your workflow. For example, a captioning workflow can load an image, generate a description, and use Save Text File to save the description under the image’s filename.
For videos, the loader extracts frames and supplies them together as an IMAGE batch. Your workflow can then process the selected frames rather than loading the video as a single still image. The frames you receive depend on the frame mode you choose.
ComfyUI-BatchFolderTools Features
Load Image From Folder (Batch)
This node loads one image at a time. In sequential mode, its counter advances automatically each time the workflow executes. It supports PNG, JPG, JPEG, WebP, BMP, TIFF, and GIF files.
Alongside the IMAGE, it outputs the folder path, the filename with and without its extension, the current index, and the total number of images. These details can help you name outputs or see where the batch is in its run. Your source filenames do not need to follow a numbered sequence.
Load Video From Folder (Batch)
This node loads one video at a time and extracts frames as an IMAGE batch. It supports MP4, AVI, MOV, MKV, WebM, FLV, WMV, and M4V files.
Choose a frame mode to suit the task:
| Frame mode | What it selects | Example use |
|---|---|---|
first_frame | The opening frame | Checking how each video begins |
last_frame | The final frame | Checking how each video ends |
all_frames | Every frame | Processing the full visual sequence |
evenly_spaced | Frames distributed across the video; the stated default is 16 frames | Giving a captioning workflow a sample from throughout the clip |
frame_range | Frames from a selected range | Focusing on a particular portion of a clip |
The node also outputs the folder path, filename with and without its extension, current index, total number of videos, frame count, frames per second (fps), and duration in seconds. Video loading requires opencv-python.
Save Text File
Save Text File writes text using a filename that matches the source file. It is useful for keeping captions alongside the images or videos they describe.
Queue Next
Place Queue Next at the end of the workflow to keep the batch moving. After one execution finishes, it re-queues the workflow for the next file. It has both image and text inputs: connect whichever matches the last output of your processing chain. The batch stops when the loader runs out of files.
Skip Files That Already Have Captions
Both folder loaders have a skip_captioned setting. When it is true, the loader skips a source file if it finds a matching .txt, .caption, or .cap file beside it. This is particularly useful after a captioning batch is interrupted: files with existing captions are skipped without spending GPU time processing them again.
Use this setting with care for other kinds of work. It checks for caption files, not whether an upscale, style transfer, or other output has been completed.
Included Example Workflows
| Workflow file | What it demonstrates |
|---|---|
batch_caption_qwenvl_mod.json | Loading images, generating detailed captions with QwenVL-Mod, and saving text files |
batch_video_caption_qwenvl_mod.json | Loading videos, sampling 16 evenly spaced frames, generating captions, and saving text files |
Both examples require ComfyUI-QwenVL-Mod. The examples are pre-wired; supply your folder path and click Queue Prompt to start.
ComfyUI-BatchFolderTools does not provide its own image-generation or captioning model. Its loaders and queue node move files through a workflow; connected nodes, such as those in the examples, perform the creative or analytical task.
Using ComfyUI-BatchFolderTools
- Add a folder loader to your workflow, or open one of the included example workflows.
- Enter the full path to the folder in
folder_pathand set the loader tosequentialmode. - Connect the loader to the nodes that process each file. Put Queue Next at the end of the chain.
- Click Queue Prompt once. The console shows progress and displays
✅ DONEwhen the batch finishes. - To stop a run early, press Escape or click Cancel.
The folder path must be readable by the operating system running ComfyUI. Examples from the original documentation include:
| Environment | Example folder path |
|---|---|
| WSL | /mnt/c/Users/me/images |
| Linux | /home/user/images |
| macOS | /Users/me/images |
| Windows | C:\Users\me\images |
| Network share | A mounted path that the operating system can read |
If a captioning run stops partway through, set skip_captioned to true on the loader and click Queue Prompt again. The loader will skip source files with existing matching caption files and continue with the others.
For workflows using a vision-language model (VLM), the original examples also suggest keep_model_loaded: true to keep the model in VRAM between files, max_tokens: 2048 for detailed descriptions, and a temperature of 0.3 for more consistent wording or 0.6 and above for more variety. These are settings on the relevant model nodes, not separate BatchFolderTools features.
What’s New with ComfyUI-BatchFolderTools
| Version | Changes | Why they matter |
|---|---|---|
| v0.8.0 | Added skip_captioned to both loaders. Added fps and duration_seconds video outputs. Revised example captioning prompts to describe what is visible, removed audio inference from the vision-only video prompt, and fixed duplicate captions by varying the VLM seed on re-queue. Also added automated Comfy Registry publishing and updated registry metadata. | Makes interrupted captioning batches easier to resume, provides more video information to workflows, and improves the example captioning experience. |
| v0.7.x | Added the video loader with five frame modes and separated Queue Next into its own node. | Expanded batch processing to videos and made the looping step explicit in the workflow. |
| v0.6.0 | Renamed the extension to ComfyUI-BatchFolderTools. | Established its current name. |
| v0.5.x | Added self-re-queuing through a hidden PROMPT input and cache-busting. | Supported repeated execution of a workflow across a batch. |
| v0.1.0–v0.4.x | Initial development. | Established the extension’s foundations. |
Troubleshooting ComfyUI-BatchFolderTools
The batch stops before processing the files I expected.
- Check that
folder_pathpoints to the intended folder and that ComfyUI can read it. - Confirm that the files use a format supported by the image or video loader you selected.
- If
skip_captionedistrue, check whether matching.txt,.caption, or.capfiles already exist beside the source files. Those sources will be skipped. - Check the console for the batch’s progress and completion message.
My workflow processes only one file.
- Confirm that the loader is set to
sequential. - Make sure Queue Next is at the end of the workflow.
- Connect its
imageortextinput to the appropriate last output in your chain, then start the workflow with Queue Prompt.
A video does not load.
- Check that it is in one of the listed video formats.
- Confirm that
opencv-python, which the video loader requires, is available in the environment running ComfyUI. - Check that the folder path is readable by that environment.
How do I resume a stopped captioning batch?
Set skip_captioned to true on the image or video loader, then click Queue Prompt again. Files with matching caption files beside them will be skipped.
Will skip_captioned detect finished upscales or other non-caption outputs?
No. The documented check looks for .txt, .caption, or .cap files beside each source file. Do not treat it as a general check for completed outputs.
Do I have to rename my files into a numbered sequence?
No. The original documentation states that filenames do not need to be sequential.
Does the extension generate captions by itself?
No. It loads files and moves them through your workflow. The included captioning examples use ComfyUI-QwenVL-Mod for caption generation.
Learn More about ComfyUI-BatchFolderTools
Start with the included batch_caption_qwenvl_mod.json and batch_video_caption_qwenvl_mod.json workflows if you want to see how the loader, captioning nodes, text output, and Queue Next fit together. For the captioning nodes used in those examples, see the ComfyUI-QwenVL-Mod project.
The extension is released under the MIT license.
