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.
> [!WARNING] > **WIP (Work in Progress) — Download and use at your own risk!** > This project is still under active development and some features may be unfinished or contain bugs.
🔹 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. **Detection**: If the workflow references model files that are missing from your directories, the extension alerts you immediately. 3. **Resolve**: * **Local Search**: Click the local search button to find similar filenames you already have on disk (e.g., if they were moved to a different subfolder). * **Online Search**: If the file isn't on disk, search for it online (e.g., on CivitAI via its SHA256 file hash or text search). 4. **Download or Link**: * Click **Download** to asynchronously download the model in the background directly into the correct ComfyUI folder. * Or select a local alternative suggested by the Fuzzy Matching algorithm. 5. **Apply**: Click the apply button to update the ComfyUI workflow 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 and Aria2 Model Resolver supports two download engines configured in the Settings panel: 1. **Python Engine**: * Out-of-the-box download backend using standard libraries (`urllib` / `aiohttp`). * No external binaries required. 2. **Aria2 Engine (Recommended)**: * High-performance, multi-threaded downloader. * Speeds up large downloads by splitting files and downloading across multiple connections (up to 16 connections/splits). * Automatically forwards target cookies, headers, and authentication tokens safely. > [!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: ```bash cd ComfyUI/custom_nodes/ ``` 2. Clone this repository: ```bash git clone https://github.com/Azornes/comfyui-model-resolver.git ``` 3. Start or restart ComfyUI. The extension will automatically install any missing dependencies (`requests`, `aiohttp`) and load the web interface. --- ## 📝 Requirements * Python 3.10 or newer * Libraries: `requests`, `aiohttp` (installed automatically if missing) * 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](https://github.com/sponsors/Azornes)