ComfyUI_SmartModelLoader Introduction
ComfyUI_SmartModelLoader helps you build image-generation workflows without filling your ComfyUI canvas with connections between every model component and setting. Its main feature is a PIPE: one connection that carries your model, text encoder (CLIP), VAE, latent, image dimensions, sampler settings, seed, and model names between compatible nodes.
You can use the adaptive Smart Model Loader for a compact, all-in-one starting point, or choose separate loaders when you want to control individual components. The extension also includes prompt-conditioning tools, a PIPE-based sampler, reusable LoRA stacks, model-file downloads, and specialized tools for supported workflows.
Overview of a workflow connecting loaders, text encoders, and the PIPE sampler
How ComfyUI_SmartModelLoader Works
Think of a PIPE as a labeled kit containing the parts and settings your workflow needs. Instead of connecting the model, VAE, seed, and other values separately at every stage, you pass the kit along one connection. A downstream node can read what it needs, change a value, and pass an updated PIPE onward.
A typical image workflow follows these steps:
- Load a model. The Smart Model Loader places the selected components and settings into a PIPE.
- Describe the image. A text-encoding node turns your prompt into conditioning, the information the model uses to guide generation.
- Generate and decode.
Eclipse KSampler (Pipe)uses the model from the PIPE, samples an image latent, and uses the VAE to decode it into a viewable image. It returns both the result and an updated PIPE.
A latent is an intermediate image representation rather than a finished picture. A VAE converts between that representation and a viewable image. A LoRA is an optional model adjustment that can influence a particular look or subject.
You do not have to expose every setting at once. The Smart Model Loader starts with common controls; its feature chips reveal additional controls only when your workflow calls for them. Your saved workflow retains which sections you enabled.
Default Smart Model Loader with its compact set of controls
ComfyUI_SmartModelLoader Features
An adaptive loader and reusable templates
Open the loader’s feature bar to enable sections such as templates, clip, vae, audio_vae, latent, sampler, lora, model_sampling, block_swap, memory_cleanup, integrity, and seed. For example, enable lora when you want a model adjustment, or sampler and seed when you want those generation settings available on the loader. Inactive sections stay out of the way. Block swap is disabled when ComfyUI’s native dynamic VRAM management already handles that task.
Feature-chip bar showing optional loader sections
Templates let you restore a saved combination of enabled sections and settings. Enable templates, choose Load, and select a bundled or saved template. Delete Template deletes that saved configuration, not its model files. Templates are stored in ComfyUI/custom_nodes/ComfyUI_SmartModelLoader/templates/.
A template can refer to a model you have not installed. Loading it does not start a download. Instead, the loader keeps the filename visible with a (missing) marker and, when saved identity information is available, offers Download from CivitAI. The bundled Krea2_RedCraft example restores its related CLIP, external VAE, sampler settings, and missing UNet reference. You decide whether to press the download button.
Template with a missing model reference and an explicit download action
Direct loaders and PIPE inspection
For a modular setup, use Model Loader, Model Loader Pipe, CLIP Loader, or either VAE loader to select components separately. IO Checkpoint Loader can combine direct components with an incoming PIPE, override values, and expose the result on individual sockets. This is useful when a node needs a specific connection, such as a model or sampler setting, rather than the whole PIPE.
Modular loaders and IO Checkpoint Loader in a workflow
Prompt conditioning
CLIP Text Encode prepares ordinary scheduled conditioning from connected text. Its Advanced counterpart adds a multiplier and Krea2 layer-rebalancing presets for workflows that need those controls. Conditioning Zero Out clears conditioning tensors and can use a known model’s base token length. Specialized encoders are also included for Qwen Image 2.1 image prompts and MiniMax Music 3 caption-and-lyrics input.
Basic and advanced text encoders alongside Conditioning Zero Out
Sampling and previews
Eclipse KSampler (Pipe) takes positive and negative conditioning, accepts an image or latent input, and reads the model and VAE from its PIPE. It returns the sampled latent, decoded image, and a copied PIPE containing the results. Its controls include how PIPE values and node widgets take precedence, tiled VAE decoding, preview modes, and queue-time seed behavior. For example, a workflow that needs to reuse the result downstream can pass along the returned PIPE instead of rebuilding its connections.
PIPE sampler and related controls
Qwen Image 2.1 scheduling
Qwen Image 2.1 Scheduler, found under Smart Model Loader → Sampler, builds a SIGMAS schedule for a custom sampler. Use it in place of BasicScheduler when you want its Qwen shift anchors and terminal stretch. It reads the connected target latent to determine image size; it does not need a model input.
Set steps and denoise on the scheduler, or connect them from IO Checkpoint Loader. They are not inherited automatically from the PIPE. Dynamic shifting uses the 256 / 0.5 and 8192 / 0.9 anchors with an exponential transform by default. The default shift_terminal of 0.02 sets the last positive sigma before the final zero. Turn dynamic shifting off to use the separate shift control.
To use the schedule, connect the scheduler’s sigmas output to SamplerCustomAdvanced → sigmas. Connect the same target latent to both the scheduler’s latent input and the custom sampler’s latent_image input. For image edits, use the Qwen encoder’s target latent in both places. The loader’s scheduler dropdown does not control this separately connected SIGMAS schedule. See the complete Qwen scheduler controls and defaults.
Qwen Image 2.1 Scheduler controls
Example custom-sampler connections using a shared target latent
LoRA, PuLID, and model downloads
Lora Stack builds a reusable stack of up to ten LoRAs; Lora Stack apply applies it to standard models or supported Nunchaku Flux, Qwen, and ZImage models. The Nunchaku PuLID loader and apply nodes provide identity guidance for a Nunchaku Flux model when the compatible nunchaku package and PuLID dependencies are present.
Download Manager (Beta) lets you inspect an exact CivitAI AIR, hash, or URL, or a Hugging Face repository. You then select compatible files, choose their registered model destinations, and monitor a persistent download queue. This is useful when you need the specific file a workflow references, rather than another file with a similar name.
Download Manager inspection, file selection, and queue controls
ComfyUI_SmartModelLoader Models
The extension does not provide a fixed list of downloadable model files. It provides loaders and tools for these model types and components:
| Type or component | When you might use it |
|---|---|
| Checkpoint | A straightforward workflow using a model with built-in components. This is the Smart Model Loader’s default path. |
| UNet | A modular workflow in which you choose components such as CLIP and VAE separately. |
| Nunchaku | A compatible Nunchaku workflow, including supported LoRA and Flux PuLID operations. It requires its compatible Python package. |
| GGUF | A workflow using a compatible GGUF model file. It requires its compatible Python package. |
| External CLIP | A setup that needs separately loaded text encoders; the CLIP loader supports one to four. |
| External VAE | A setup that needs a separately selected image or video VAE. A dedicated loader can select separate video and audio VAEs. |
These are loading options, not promises that one type will produce a particular artistic style or run faster on your computer. The model file and the rest of your workflow determine the creative result.
What’s New with ComfyUI_SmartModelLoader
The provided documentation does not include a version-by-version changelog. It does describe these current capabilities and compatibility changes:
- Nodes 2.0-ready tools: The loader, LoRA Stack, and Nunchaku PuLID tools are available in the current node set.
- Older workflow import: Workflows and generated images using
Smart Model Loader v2 [Eclipse]orIO Checkpoint Loader v2 [Eclipse]import into the current nodes, including inside subgraphs. Saved settings and connections are retained, and the original file remains unchanged. Save the loaded workflow to retain the updated IDs. - Preserved
[Eclipse]identifiers: These suffixes keep historical workflows compatible. ComfyUI Eclipse is optional; it is not required to run these nodes. - Template recovery and explicit downloads: A missing primary model referenced by a template can remain visible with its saved identity and an offered download action, without starting a transfer automatically.
- Qwen Image 2.1 tools: Dedicated prompt encoding and scheduling support the custom-sampler path described above.
Troubleshooting ComfyUI_SmartModelLoader
A template shows (missing) beside its model
- Check the referenced filename and the destination shown by the loader.
- If Download from CivitAI appears, review the file and destination before pressing it. Loading the template alone does not download anything.
- After the requested file has been acquired and the node refreshes, check that the missing marker is gone.
See the illustrated missing-model example and the Download Manager guide.
A Nunchaku, GGUF, or PuLID option is unavailable
- Confirm which model type or tool the workflow needs.
- Check whether its compatible Python package is available in your ComfyUI environment. PuLID also needs its PuLID dependencies.
- If you are using a standard checkpoint or UNet workflow, continue with those loaders and the other available tools; these optional packages are not required for the standard path.
For PuLID-specific CUDA problems, consult the Nunchaku PuLID CUDA troubleshooting guide.
A Qwen custom sampler is not following the steps or denoise value you expected
- Inspect the steps and denoise inputs on
Qwen Image 2.1 Scheduler. PIPE values do not flow into them automatically. - Connect the corresponding outputs from
IO Checkpoint Loaderif you want those values to drive the scheduler; otherwise, use the scheduler’s own controls. - Confirm that the scheduler’s
sigmasoutput goes toSamplerCustomAdvanced → sigmas. - Confirm that the scheduler and custom sampler receive the same target latent.
The Qwen wiring diagram shows these connections.
Frequently asked questions
Do I need ComfyUI Eclipse because some nodes say [Eclipse]?
No. Those names are compatibility identifiers. Smart Model Loader provides the implementations, and Eclipse is optional.
Will loading a template download its missing model automatically?
No. A download starts only when you choose the offered action.
Will deleting a template delete my models?
No. Delete Template removes the saved configuration, not model files.
Can I still use an older workflow?
The documented older Smart Model Loader v2 and IO Checkpoint Loader v2 [Eclipse] workflows import into current nodes while retaining their saved values and connections. Save the loaded workflow to keep the updated IDs.
Do I have to use a PIPE everywhere?
No. Standalone loaders and IO Checkpoint Loader expose individual connections when a modular workflow needs them.
Learn More about ComfyUI_SmartModelLoader
- Smart Model Loader reference: loader features and detailed controls.
- Standalone loaders: choosing and connecting model components individually.
- Pipeline nodes: working with PIPE-based generation.
- Download Manager guide: inspecting, selecting, and acquiring model files.
- Nunchaku PuLID CUDA troubleshooting: help for that specialized workflow.
- Security model: how model loading and downloads are handled.
