Model-Resolver

Find missing models in ComfyUI, download them from supported sources, and update workflow paths.

🔹 Quick Start   |   ⚙️ Configuration

ModelResolverShowTime_v1.mp4

---

Key Features

• Find local matches. ModelResolver scans ComfyUI model directories and compares missing filenames with files on disk. It ignores case, extensions, and small naming changes, then shows a similarity score.
• Search supported sources. Find files on CivitAI, Hugging Face, CivArchive, Lora Manager Archive, and the ComfyUI-Manager model database.
• Update workflows. Replace model names and paths in the active workflow, including nested subgraphs and loaders from rgthree's Power Lora Loader and LoraManager.
• Manage downloads. Send files to their model folders, track speed and progress, and cancel or pause downloads when the selected backend supports it.
• Work in batches. Queue exact local matches, search several missing models, download known sources together, and review active downloads or history.
• Inspect loaded models. Review the models used by the active workflow, their physical paths, strength values, and disk status.
• Open model folders. Reveal a model file in the host file manager when the platform supports that action.
• Use custom URLs. Download a file from any direct URL and choose its target folder and filename.

---

How It Works (Step-by-Step)

1. Load Workflow: Load any workflow JSON or image into ComfyUI.
2. Open Model Resolver: Open the Model Resolver interface using one of these options:
   • Click the Model Resolver tab icon in the ComfyUI sidebar (or the menu/topbar button in older ComfyUI versions).
   • Press the default keyboard shortcut Ctrl + Shift + |.
   • Add a Model Resolver Opener node to your canvas and click its Open Model Resolver button.
   • Search for Open Model Resolver in the ComfyUI Command Palette.
3. Detection: Once opened, the extension automatically scans your active workflow, checks your local directories, and lists any referenced models that are missing on disk.
4. Resolve:
   • Local Search: Click the search icon next to a missing model to find similar filenames already on your disk (e.g., if you renamed a file or moved it to a different subfolder).
   • Online Search: If the file isn't on disk, search for it online (e.g., on CivitAI via its SHA256 hash or text search, or on HuggingFace).
5. Download or Link:
   • Click Download to asynchronously download the model in the background directly into the correct category folder.
   • Or select a local alternative suggested by the Fuzzy Matching algorithm.
6. Apply: Click Apply to update the ComfyUI workflow nodes with the resolved model paths, then queue the prompt.

The dialog has Missing Models, Loaded Models, and Options tabs. Its queue panel keeps pending links separate from downloads, with active progress and download history.

---

Supported Nodes & Model Types

Model Resolver supports standard ComfyUI mechanisms as well as custom implementations of popular loader nodes:

• Standard loaders: CheckpointLoader, LoraLoader, VAELoader, ControlNetLoader, UpscaleModelLoader, etc.
• Advanced loaders: Nodes from the LoraManager suite (LoraLoaderV2, Lora Loader, Lora Stacker), rgthree (Power Lora Loader), and LTX-Video nodes.
• Subgraphs: Full support for scanning and updating nodes inside nested group subgraphs.

---

Downloader Backends

Model Resolver provides two download engines in the Settings panel and an automatic Hugging Face Xet transport for eligible files:

Backend / transport	How it is selected	Live progress	Cancel	Pause / resume
Python	Selected in Settings; also used as the general fallback	Yes	Yes	No
Aria2 (Optional)	Selected in Settings	Yes	Yes	Yes
Hugging Face Xet	Activated automatically for Xet-backed Hugging Face files while the Python engine is selected	Yes, using native Xet updates	Yes	No

Python Engine

• Works out of the box without external downloader binaries.
• Supports authenticated Hugging Face and CivitAI requests, live speed and ETA, and cancellation with partial-file cleanup.

Aria2 Engine

• High-performance, multi-connection downloader for large files.
• Splits downloads across multiple connections (up to 16 connections/splits).
• Safely forwards target cookies, headers, and authentication tokens.
• Supports cancelling, pausing, and resuming partial downloads.

Hugging Face Xet Transport

• Uses the official huggingface-hub and hf-xet packages for files stored with Hugging Face Xet.
• Starts automatically when the Python engine is selected and the Hugging Face response includes Xet metadata. If Xet is unavailable or the file is not Xet-backed, Model Resolver falls back to the regular Python downloader.
• Reports native transfer progress, network speed, and ETA approximately every 200 ms. The progress display uses the known final file size from Hugging Face metadata.
• Writes an in-progress download to a temporary .xet-part file. Cancelling stops the native Xet task and removes this partial file.
• May briefly show Finalizing after the network transfer while Xet reconstructs and writes the final model file.

Note

Xet transfers compressed, deduplicated data. The received byte count can stay below the final model size, so a download can reach Finalizing before the network counter reaches the final size.

Tip

Install and configure aria2 from the Settings panel when you need pause/resume or segmented transfers. Model Resolver downloads the official release for your operating system and architecture, extracts it, and manages the background daemon.

---

Dynamic path templates

Use model metadata to build download paths. The Download Path Mode setting provides three options:

• suggested: choose a subfolder category from the available metadata.
• manual: use your custom path mapping.
• template: build a relative path with template variables.

Template variables

• {base_model}: base architecture such as SD 1.5, SDXL, or Flux. Base Model Path Mappings can rename values such as sd1.5 and flux1.
• {author}: creator name or Hugging Face repository publisher.
• {first_tag}: primary model tag, selected from categories such as style, concept, and character.
• {model_name}: cleaned model name or file stem.
• {version_name}: release version such as v1.0.

Default templates

• Loras: {base_model}/{first_tag}
• Checkpoints: {base_model}
• Embeddings: {base_model}

For example, a Lora can use Loras/SDXL/style/my_lora_v1.safetensors, while a checkpoint can use Checkpoints/Flux/my_flux_model.safetensors.

---

Configuration & Settings

Open Settings to add credentials for downloads and searches:

• CivitAI API key and session token: download NSFW models and files that require accepted terms.
• Hugging Face access token: download files from gated or private repositories.
• Brave Search API key: find public or gated Hugging Face download links through fallback search.

The Settings panel includes Check buttons for each credential type. Use them to verify a key or token before starting a download.

You can also enable or disable search sources, choose CivitAI and Hugging Face fallback methods, set automatic base-model and subfolder suggestions, configure aria2, control workflow metadata, and export logs. The wiki contains the full settings reference.

Workflow Metadata and the Opener Node

• Embed workflow hashes stores SHA-256 metadata for referenced models in saved workflows and image workflow JSON. Later scans can identify a renamed file by its hash.
• Embed opener node adds a small Model Resolver Opener node to saved workflows. Its button opens the resolver, and its dependency metadata helps ComfyUI-Manager identify the extension.
• Open when a workflow has missing models opens the resolver after analysis finds unresolved references. This option is disabled by default.

The opener node only opens Model Resolver. It has no image, model, or prompt outputs. Add it from Options or the ComfyUI Command Palette.

Local Databases and Maintenance

The Options tab can update the ComfyUI-Manager model database, refresh the CivitAI base-model list, and refresh the Hugging Face author index. It also includes a metadata-size audit, a local SHA-256 metadata builder, cache controls, and frontend/backend log export.

See the wiki maintenance guide for details.

---

Loaded Models Inspector & Local Hashing

• Loaded Models Tab: Check what models are loaded in the current active Python session. It lists paths, model categories, byte sizes, physical existence checks, strength values, and active/inactive state.
• Open Containing Folder: Select a model in the Loaded Models tab and click the folder icon to reveal it in the host system's file manager.
• Model details: Open source information, previews, descriptions, tags, versions, and trained words when the provider exposes them.
• Local Hashing (sha256):
  • You can calculate the exact sha256 hash of any local model file in the background.
  • Hashing status is updated in real-time, allowing you to use exact hash queries on CivitAI/CivArchive to retrieve model metadata and link files.

---

Installation

Install via ComfyUI-Manager

1. Search ComfyUI Model Resolver in ComfyUI-Manager and click the Install button.
2. Restart ComfyUI.

Manual Install

1. Navigate to the custom_nodes folder in your ComfyUI installation:

   cd ComfyUI/custom_nodes/

2. Clone this repository:

   git clone https://github.com/Azornes/Comfyui-Model-Resolver.git

3. Enter the repository:

   cd Comfyui-Model-Resolver

4. Install the required dependencies:
   • For Windows Portable Version:

     ..\..\..\python_embeded\python.exe -m pip install -r requirements.txt

   • For standard Python/virtual environment installations: Activate the same Python environment used by ComfyUI, then run:

     pip install -r requirements.txt

5. Start or restart ComfyUI.

---

Requirements

• ComfyUI 0.26.0 or newer
• Python 3.10 or newer
• Libraries: requests, aiohttp, rapidfuzz, huggingface-hub
• Modern web browser with JS support (Chrome, Edge, Firefox, Brave)

Hugging Face Xet support is optional. When the Xet transport is unavailable, Model Resolver uses the regular Python downloader.

Backend Architecture

The ComfyUI entry point stays small. Runtime state lives in core/extension.py, route registration lives in core/routes/registry.py, HTTP adapters live in core/routes/, and shared feature logic lives in core/services/.

See docs/architecture.md for the dependency flow and local verification commands.

For user workflows, provider settings, download paths, metadata, and troubleshooting, see the Model Resolver wiki.

---

License

This project is licensed under the MIT License. Feel free to use, modify, and distribute.

---

Support / Sponsorship

• Star the repository if ModelResolver helps your workflows.
• Report a bug or suggest a feature.
• Support the project through GitHub Sponsors or Ko-fi.