ComfyUI-Model-Batch-Downloader Introduction
ComfyUI-Model-Batch-Downloader is a custom node for downloading several model files as part of a ComfyUI workflow. Instead of downloading each file in a browser and moving it into the right folder yourself, you can give the node a list of links and tell it where each file belongs. The downloader supports Hugging Face, Civitai, and other HTTP or HTTPS download URLs.
This is useful when a workflow needs several separate files, such as a diffusion model, a text encoder, and a VAE. The downloader processes the list in order and can pass its results to companion loader nodes within the same ComfyUI queue. It also works as a standalone download step when you do not need to load the files immediately.
The extension does not include model weights or create images on its own. You choose the files and their destinations. It will not overwrite an existing completed file, but it also does not verify file checksums, so you should obtain links from sources you trust.
How ComfyUI-Model-Batch-Downloader Works
Think of a download list as a packing list for your workflow. Each entry tells the extension:
- Where to get a file: its download URL.
- Where to put it: a model category such as
checkpoints,loras, orvae, plus an optional subfolder. - What to call it: an optional filename and an
idthat other nodes can use to identify the result.
When you run the workflow, the downloader saves each file in the corresponding ComfyUI model directory. It uses the external aria2c download program to transfer files. If a previous transfer left an .aria2 sidecar file, it attempts to resume that transfer. If a completed destination file already exists, it skips the download rather than replacing it.
To use a file immediately, connect the download node’s download_result output to the appropriate Downloaded loader. In that loader, enter the same id used by the file’s download-list entry. The ID acts like a label on your packing list: it tells the loader which downloaded file to pick.
For example, a workflow with separate Anima components could download its diffusion model to diffusion_models, its text encoder to text_encoders, and its VAE to vae. Each component would then go to its matching loader. These are examples of file organization, not a guarantee that any particular combination of model files is compatible.
ComfyUI-Model-Batch-Downloader Features
Two ways to make a download list
Model Download Batchprovides a list interface with add and remove buttons. It stores the list internally as JSON, so you do not need to write JSON to use the interface.Model Download Batch (JSON)accepts the list directly as JSON. This can be useful when you already have a prepared manifest or want to inspect the entries as text.
Both nodes use the same download behavior. Both also have a passthrough input and output, allowing you to place a download step in an existing connection. They can run unconnected as output nodes, too.
Downloaded loader nodes
These nodes use download_result and a manifest id to load a file from the matching category:
| Loader | File category | What it loads |
|---|---|---|
Load Checkpoint (Downloaded) | checkpoints | An all-in-one checkpoint |
Load Diffusion Model (Downloaded) | diffusion_models | A separate diffusion model |
Load CLIP (Downloaded) | text_encoders | A text encoder |
Load VAE (Downloaded) | vae | A VAE |
Load ControlNet (Downloaded) | controlnet | A ControlNet model |
Load Upscale Model (Downloaded) | upscale_models | An upscale model |
Load LoRA (Downloaded) | loras | A LoRA |
These follow the behavior of the corresponding standard ComfyUI loaders. Load CLIP (Downloaded) offers the same type choices as ComfyUI’s standard Load CLIP, including krea2, ideogram4, and flux2; select the type appropriate for the text encoder you are loading. For a model-only LoRA, you can set strength_clip to 0.
Destinations for other model files
The downloader supports thirteen destination categories in total. A category determines where a file is saved; it does not mean the downloader includes a loader for every category.
model_type | Default destination | How the file can be used |
|---|---|---|
checkpoints | models/checkpoints | Load Checkpoint (Downloaded) |
diffusion_models | models/diffusion_models | Load Diffusion Model (Downloaded) |
text_encoders | models/text_encoders | Load CLIP (Downloaded) |
vae | models/vae | Load VAE (Downloaded) |
loras | models/loras | Load LoRA (Downloaded) |
controlnet | models/controlnet | Load ControlNet (Downloaded) |
embeddings | models/embeddings | References in ComfyUI prompts; no companion loader |
upscale_models | models/upscale_models | Load Upscale Model (Downloaded) |
onnx | models/onnx | Impact Pack |
sam3 | models/sam3 | The path-based (down)Load SAM3 Model in comfyui-sam3 |
llm | models/llm | LLM Model Loader or LLM GGUF Model Loader in ComfyUI_LLM_SDXL_Adapter |
ultralytics_bbox | models/ultralytics/bbox | Impact Subpack |
ultralytics_segm | models/ultralytics/segm | Impact Subpack |
If ComfyUI has a configured folder path for a category, that path takes precedence over the default shown here. The optional subfolder places a file beneath the selected category’s model root.
The external consumer nodes in the table are not included with this downloader. For example, placing a file in models/sam3 does not add a SAM3 loader to your workflow. The default path models/sam3/sam3.pt used by the path-based comfyui-sam3 loader matches this downloader’s default SAM3 destination. Likewise, LLM support means downloading a single file to models/llm; it does not download an entire repository or set up multi-file inference.
Progress and download handling
While a batch runs, ComfyUI shows its standard progress bar. For multiple files, the bar advances across the whole batch rather than starting over for each file. About once per second, the ComfyUI log reports the current ID, percentage, speed, and estimated time remaining.
The downloader attempts every entry in order. If one fails, it still attempts the remaining entries and reports failures together at the end. Duplicate IDs and duplicate destinations within one list are errors. Destinations are restricted to configured ComfyUI model roots.
Download-list fields
A direct JSON manifest is an array with at least one entry. Each entry can contain:
| Field | Required? | Meaning |
|---|---|---|
url | Yes | The file’s HTTP or HTTPS download URL |
model_type | Yes | One of the thirteen destination categories above |
subfolder | No | A folder beneath the selected model root |
filename | No | The saved filename; otherwise resolved from the response or URL |
id | No | The label used by a Downloaded loader; otherwise the filename without its final extension |
split | No | A value from 1 to 16; defaults to 16 |
For example, if the resolved filename is model.fp16.safetensors and you omit id, its ID is model.fp16. Giving important files explicit IDs makes loader references easier to recognize and keeps them stable if a source changes its filename. For a URL that does not reveal a filename, such as a Civitai API URL, the list interface offers Resolve filename / ID.
Here is an illustrative three-file manifest. Replace the example URLs with links to the actual files you intend to use:
[
{
"url": "https://huggingface.co/owner/repo/resolve/main/anima-model.safetensors",
"model_type": "diffusion_models",
"subfolder": "anima",
"id": "anima_model",
"split": 16
},
{
"url": "https://huggingface.co/owner/repo/resolve/main/qwen3-0.6b.safetensors",
"model_type": "text_encoders",
"subfolder": "anima",
"id": "anima_encoder"
},
{
"url": "https://huggingface.co/owner/repo/resolve/main/qwen-image-vae.safetensors",
"model_type": "vae",
"id": "qwen_vae"
}
]
Connect download_result to the corresponding diffusion-model, CLIP, and VAE Downloaded loaders. Enter anima_model, anima_encoder, and qwen_vae in those loaders, respectively.
For a Civitai LoRA, the author recommends the civitai.red download domain:
[
{
"url": "https://civitai.red/api/download/models/{modelVersionId}",
"model_type": "loras",
"id": "civitai_lora",
"filename": "civitai_lora.safetensors"
}
]
Replace {modelVersionId} with the version ID for the file you intend to download. The author notes that civitai.com download URLs are deprecated for this custom node and may return HTTP 403, particularly for restricted or NSFW files.
Private downloads
If a source requires an access token, the downloader reads it from the environment that starts ComfyUI:
| Service | Environment variable |
|---|---|
| Hugging Face | HF_TOKEN |
| Civitai | CIVITAI_API_TOKEN |
Do not put tokens in a node or workflow JSON. Tokens are sent only to their corresponding domains and are not stored in the manifest, download_result, or the interface state. Authentication tokens and authenticated URLs are not written to the download log.
Troubleshooting ComfyUI-Model-Batch-Downloader
The node says aria2c is required.
- Check whether
aria2c --versionworks in the same environment used to start ComfyUI. - If it does not, make
aria2cavailable on that environment’sPATH. The downloader does not bundle or automatically install it. - Restart ComfyUI so the running process can see the updated environment.
A Hugging Face download returns HTTP 401 or 403.
- Confirm that the link points to a file you can access.
- If access requires a token, check that
HF_TOKENis set for the process that starts ComfyUI. - Check that your account has permission to access the repository. A token does not grant access to files your account is not permitted to download.
A Civitai download returns HTTP 401 or 403.
- Use the recommended
https://civitai.red/api/download/models/{modelVersionId}URL format with the correct version ID. - If the file requires authentication, check
CIVITAI_API_TOKENin the environment that starts ComfyUI. - If you used a
civitai.comdownload URL, try the recommended domain; the former may fail even with a valid token.
The downloader reports duplicate id.
Give each entry a different explicit id. A Downloaded loader uses that ID to select a result, so two entries in the same manifest cannot share it.
A Downloaded loader reports a category mismatch.
Check the entry’s model_type, then connect download_result to its matching loader. For example, a vae entry belongs with Load VAE (Downloaded), not Load Checkpoint (Downloaded).
The file downloaded, but there is no Downloaded loader for its category.
Check the destination table above. Categories such as sam3, llm, and ultralytics_bbox are download destinations, but their consumer nodes come from separate extensions. Embeddings are used through prompt references rather than a companion loader.
A file was skipped, or a download appears to resume.
A completed file at the destination is skipped without being overwritten. If a matching .aria2 sidecar exists, the downloader attempts to continue the incomplete transfer. Because the extension does not verify checksums, a skipped file is not proof that its contents are correct.
Frequently asked questions
Does this extension supply models?
No. It downloads files from URLs you provide and places them in the selected ComfyUI model categories.
Can I download from a site other than Hugging Face or Civitai?
Yes. The manifest accepts HTTP and HTTPS URLs. The link must lead to a file the downloader can access.
Do I have to use JSON?
No. Model Download Batch provides a list interface. Use Model Download Batch (JSON) when you prefer to provide the list directly.
Can I download several files and use them in one workflow run?
Yes. Connect download_result to the appropriate Downloaded loaders and give each loader the ID of the file it should use.
Will this replace models I already have?
No. An existing completed destination file is marked as skipped rather than overwritten.
Do external consumer extensions come with the downloader?
No. Impact Pack, comfyui-sam3, ComfyUI_LLM_SDXL_Adapter, and Impact Subpack are separate projects used only if your workflow needs their nodes.
Learn More about ComfyUI-Model-Batch-Downloader
- ComfyUI-Model-Batch-Downloader repository: The author’s project page for the extension and its documentation.
- Japanese README: An alternative-language version linked from the original README.
