ModelResolver – Relink missing models and download from HuggingFace/CivitAI

ModelResolver is a powerful ComfyUI extension for automatically resolving missing models in loaded workflows. It features intelligent local fuzzy matching, direct cloud downloads, background download tracking, and automated in-place workflow updating.

🔹 Quick Start   |   ⚙️ Configuration

---

🚀 Key Features

• 🔍 Intelligent Fuzzy Matching: Scans local ComfyUI model directories and looks for similar files (ignoring case, extensions, or minor naming differences) with similarity confidence scores.
• ☁️ Multi-Source Cloud Downloader: Searches for and downloads missing files from CivitAI, HuggingFace, CivArchive, Lora Manager Archive, and the ComfyUI-Manager model database.
• 🔄 In-Place Workflow Updater: Safely replaces model names and paths in your current workflow (supporting nested subgraphs and custom nodes like rgthree's Power Lora Loader or LoraManager).
• 📥 Background Download Manager: Downloads models asynchronously directly to the correct directories (checkpoints, loras, vae, etc.) with speed tracking, file size display, progress bars, and cancellation/pause support.
• 🕵️ Loaded Models Inspector: A dedicated tab displaying all models used in the active workflow, including their strength, physical paths, and disk availability status.
• 📂 Open Containing Folder: Quickly opens Windows Explorer and selects/highlights the model file directly from the interface.
• 🔗 Custom URL Downloads: Directly paste any custom URL link to download files into target folders with customized names.

---

🛠️ 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 new, correct model paths. You're ready to click Queue Prompt!

---

📂 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 (Recommended)	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 and deduplicated data, so the number of bytes received over the network can be lower than the final model file size. In that case the download can enter Finalizing before the displayed network byte counter reaches the final file size.

Tip

One-Click Aria2 Setup: You do not need to install aria2c manually. The extension features a built-in installer that downloads, extracts, and configures the latest official release matching your OS architecture (Windows, macOS, Linux) with a single click in the Settings panel.

The extension also manages the lifecycle of the aria2 background daemon, automatically starting it when a download starts and stopping it when it remains idle to preserve system resources.

---

📂 Dynamic Path Templates

When downloading a new model, you can let Model Resolver organize your files automatically based on metadata using templates. The extension offers three Download Path Modes:

• suggested: Guesses the best subfolder category automatically.
• manual: Standard custom path mapping.
• template: Dynamically generates the relative path inside your model category using variables.

Available Template Variables

• {base_model}: The base model architecture (e.g., SD 1.5, SDXL, Flux). The value can be translated to customized names via Base Model Path Mappings (e.g., mapping sd1.5 to SD1.5 and flux1 to Flux).
• {author}: Creator/author username or HuggingFace repo publisher.
• {first_tag}: Primary tag from the model database (mapped via priority hierarchy such as style, concept, character, etc.).
• {model_name}: Clean model name or file stem.
• {version_name}: Model release version name (e.g., v1.0).

Default Path Templates

• Loras: {base_model}/{first_tag} (e.g., Loras/SDXL/style/my_lora_v1.safetensors)
• Checkpoints: {base_model} (e.g., Checkpoints/Flux/my_flux_model.safetensors)
• Embeddings: {base_model}

---

⚙️ Configuration & Settings

Configure credentials and API keys in the Settings panel to authenticate gated downloads:

• CivitAI API Key & Session Token: Required to download NSFW models or those requiring accepted terms of service.
• HuggingFace Access Token: Required for gated, private repositories.
• Brave Search API Key: Fallback search query key to locate public/gated HuggingFace download links.

Important

Built-in Connection Testers: The options panel contains instant Check buttons for CivitAI keys, CivitAI Session Tokens, HuggingFace tokens, and Brave Search keys. You can verify if credentials are valid and active without leaving the interface.

---

🕵️ 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, and confidence levels.
• Open Containing Folder: Select a model in the Loaded Models tab and click the folder icon to open Windows Explorer with the target file highlighted.
• 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

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

---

📜 License

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

---

💖 Support / Sponsorship

• ⭐ Give a star — it means a lot to me!
• 🐛 Report a bug or suggest a feature.
• 💖 Support my work: 👉 GitHub Sponsors