{
  "$type": "site.standard.document",
  "bskyPostRef": {
    "cid": "bafyreiguuxm3hlsf3ooshcsi23263sdbhjyh5rxrm4q4srmdihj46xylgm",
    "uri": "at://did:plc:pgryn3ephfd2xgft23qokfzt/app.bsky.feed.post/3mkjblyzekro2"
  },
  "path": "/t/adding-a-custom-node-or-model/175608#post_2",
  "publishedAt": "2026-04-27T22:54:47.000Z",
  "site": "https://discuss.huggingface.co",
  "tags": [
    "ComfyUI custom-node installation guide",
    "ComfyUI Windows Portable guide",
    "ComfyUI Manager installation guide",
    "ComfyUI forum note on Portable Python / python_embeded",
    "ComfyUI custom-node troubleshooting",
    "Example GitHub issue with multiple (IMPORT FAILED) custom nodes",
    "Example import-failed custom-node issue",
    "ComfyUI-Copilot GitHub project",
    "Example Copilot dependency/import issue",
    "ComfyUI Models guide",
    "ComfyUI model troubleshooting",
    "ComfyUI LoRA tutorial",
    "Hugging Face / ComfyUI model-folder guide",
    "Hugging Face: Downloading models",
    "Hugging Face Hub: Download files from the Hub",
    "Getting Started with AI Image Generation",
    "ComfyUI Text-to-Image Workflow",
    "ComfyUI Manager installation",
    "Hugging Face download files guide",
    "ComfyUI-Copilot",
    "How to Install Custom Nodes in ComfyUI",
    "Custom-node troubleshooting",
    "ComfyUI Wiki: install custom nodes",
    "Example Copilot dependency issue"
  ],
  "textContent": "You seem a bit confused, so let’s just take a moment to sort things out:\n\n* * *\n\n# Adding a custom node or model in ComfyUI / Hugging Face: what is probably going wrong, and where to start\n\nYou are probably not doing one single thing wrong. The more likely problem is that ComfyUI has several different “download and install” categories that look similar from the outside but are completely different underneath.\n\nFor a beginner, these all feel like the same action:\n\n> download something → extract/copy it somewhere → maybe run `pip install` → restart ComfyUI → expect something new to appear\n\nBut in ComfyUI there are at least four different things:\n\nThing | Plain-English meaning | Usually goes here | How it appears in ComfyUI\n---|---|---|---\n**Custom node** | Extra code that adds new ComfyUI features | `ComfyUI/custom_nodes/<node_folder>` | Right-click node menu, left panel, Manager UI, workflow support, or backend feature\n**Model** | AI weights, usually a big file | `ComfyUI/models/<model_type>` | Dropdown inside a loader node\n**Python dependency** | Package a custom node needs to run | ComfyUI’s Python environment | Does not appear directly; errors show in the command window\n**Workflow** | A graph/recipe telling ComfyUI what to connect | Opened or dragged into ComfyUI | Shows missing-node or missing-model warnings if pieces are absent\n\nThat distinction is the whole issue.\n\nA `.safetensors` file is probably a **model** , not a custom node.\nA GitHub ZIP with `requirements.txt` is probably a **custom node** , not a model.\nA `.json` file or workflow PNG is probably a **workflow** , not a model or a custom node.\nA `requirements.txt` file is not something you “load” in ComfyUI; it tells Python which packages a custom node needs.\n\n* * *\n\n## My short diagnosis\n\nFrom what you described:\n\n> “I keep downloading stuff, extracting to the `comfyui/custom_nodes` folder, removing the `-main` bit, running `pip install -r requirements.txt`, all looks good, reload ComfyUI, nothing.”\n\nThe most likely causes are:\n\n  1. **You may be running the wrong`pip`.**\n  2. **The custom-node folder may be nested incorrectly.**\n  3. **The custom node may be failing to import during ComfyUI startup.**\n  4. **You may be expecting every custom node to appear as a normal right-click node.**\n  5. **ComfyUI Manager may not actually be enabled.**\n  6. **You may be mixing up Hugging Face model downloads with GitHub custom-node installs.**\n  7. **ComfyUI-Copilot is probably not the best first test because it has its own UI/activation flow.**\n\n\n\nThat is a very normal beginner situation. ComfyUI is powerful, but its installation ecosystem is not beginner-obvious.\n\n* * *\n\n# The biggest likely issue: plain `pip` may be installing into the wrong Python\n\nIf you are using **ComfyUI Windows Portable** , it has its own Python inside:\n\n\n    <ComfyUI_ROOT>\\python_embeded\\python.exe\n\n\nSo this command can be misleading:\n\n\n    pip install -r requirements.txt\n\n\nIt may install packages into your normal Windows Python, not into ComfyUI’s Python.\n\nFor ComfyUI Portable, the safer pattern is:\n\n\n    cd /d <ComfyUI_ROOT>\n    .\\python_embeded\\python.exe -m pip install -r .\\ComfyUI\\custom_nodes\\<NODE_FOLDER>\\requirements.txt\n\n\nExample for ComfyUI-Copilot:\n\n\n    cd /d D:\\ComfyUI_windows_portable\n    .\\python_embeded\\python.exe -m pip install -r .\\ComfyUI\\custom_nodes\\ComfyUI-Copilot\\requirements.txt\n\n\nWhy this matters:\n\n\n    You run pip.\n    The install looks successful.\n    Lots of text appears.\n    But the packages went into the wrong Python.\n    ComfyUI starts with its own Python.\n    The custom node tries to import a required package.\n    ComfyUI cannot find it.\n    The custom node fails to load.\n    Nothing appears in ComfyUI.\n\n\nSo “pip looked good” does not necessarily mean “ComfyUI can use it.”\n\nOfficial references:\n\n  * ComfyUI custom-node installation guide\n  * ComfyUI Windows Portable guide\n  * ComfyUI Manager installation guide\n  * ComfyUI forum note on Portable Python / python_embeded\n\n\n\n* * *\n\n# The second likely issue: the folder may be nested wrong\n\nWhen you download a GitHub ZIP, it often extracts like this:\n\n\n    ComfyUI-Copilot-main\n\n\nRenaming it to:\n\n\n    ComfyUI-Copilot\n\n\nis not always enough.\n\nYou need to check the inside of the folder.\n\n## Correct custom-node folder shape\n\n\n    ComfyUI_windows_portable\n    └── ComfyUI\n        └── custom_nodes\n            └── ComfyUI-Copilot\n                ├── __init__.py\n                ├── requirements.txt\n                ├── README.md\n                └── other files...\n\n\n## Wrong: double nested\n\n\n    ComfyUI_windows_portable\n    └── ComfyUI\n        └── custom_nodes\n            └── ComfyUI-Copilot\n                └── ComfyUI-Copilot\n                    ├── __init__.py\n                    ├── requirements.txt\n                    └── other files...\n\n\n## Wrong: extracted folder but real code is one level deeper\n\n\n    ComfyUI_windows_portable\n    └── ComfyUI\n        └── custom_nodes\n            └── ComfyUI-Copilot-main\n                └── ComfyUI-Copilot\n                    ├── __init__.py\n                    └── requirements.txt\n\n\nFor custom nodes, the actual node package should usually sit directly under:\n\n\n    ComfyUI\\custom_nodes\\<node_folder>\n\n\nnot one or two folders deeper.\n\nThat is why I would avoid ZIP installs at first. Use **Manager** first, **Git clone** second, and ZIP only if necessary.\n\n* * *\n\n# The third likely issue: the node may be failing to import\n\nA custom-node folder can exist, and the dependency install can look successful, but ComfyUI can still fail to load the node.\n\nWhen ComfyUI starts, it tries to import every custom node. If one fails, it is skipped.\n\nYou need to look in the black command window for words like:\n\n\n    IMPORT FAILED\n    Traceback\n    ModuleNotFoundError\n    ImportError\n    No module named\n    Cannot import\n\n\nExample:\n\n\n    0.0 seconds (IMPORT FAILED): D:\\ComfyUI_windows_portable\\ComfyUI\\custom_nodes\\ComfyUI-Copilot\n\n\nThat means:\n\n> ComfyUI found the custom-node folder, tried to load it, failed, and skipped it.\n\nThe node will not appear.\n\nIf you see:\n\n\n    ModuleNotFoundError: No module named 'xyz'\n\n\nthat means:\n\n> The custom node needs package `xyz`, but ComfyUI’s Python cannot find it.\n\nThen install the requirements using ComfyUI’s embedded Python, not plain `pip`.\n\nUseful references:\n\n  * ComfyUI custom-node troubleshooting\n  * Example GitHub issue with multiple (IMPORT FAILED) custom nodes\n  * Example import-failed custom-node issue\n\n\n\n* * *\n\n# ComfyUI Manager: you may need to enable it, not “install it from Essentials”\n\nThis part is very important.\n\nCurrent ComfyUI Manager behavior can differ from older tutorials.\n\nFor **Windows Portable** , the current ComfyUI docs say the new ComfyUI Manager is built into ComfyUI core, but it needs to be enabled.\n\nFrom your ComfyUI portable root folder, run:\n\n\n    cd /d <ComfyUI_ROOT>\n\n    .\\python_embeded\\python.exe -m pip install -r .\\ComfyUI\\manager_requirements.txt\n\n    .\\python_embeded\\python.exe -s .\\ComfyUI\\main.py --windows-standalone-build --enable-manager\n\n\nExample:\n\n\n    cd /d D:\\ComfyUI_windows_portable\n\n    .\\python_embeded\\python.exe -m pip install -r .\\ComfyUI\\manager_requirements.txt\n\n    .\\python_embeded\\python.exe -s .\\ComfyUI\\main.py --windows-standalone-build --enable-manager\n\n\nThen open ComfyUI in the browser.\n\nImportant: if you normally start ComfyUI by double-clicking:\n\n\n    run_nvidia_gpu.bat\n\n\nManager may disappear again unless that `.bat` file also includes:\n\n\n    --enable-manager\n\n\nOpen `run_nvidia_gpu.bat` in Notepad and look for the line that launches ComfyUI. Add `--enable-manager`.\n\nIt should look roughly like:\n\n\n    .\\python_embeded\\python.exe -s ComfyUI\\main.py --windows-standalone-build --enable-manager\n\n\nOfficial reference:\n\n  * ComfyUI Manager installation guide\n\n\n\n* * *\n\n# Why LoRA Manager worked but Copilot / Actor / Manager did not\n\nThis is not surprising.\n\nOne successful install does not prove all installs will work.\n\nLoRA Manager may have worked because it came through a clean one-click path:\n\n\n    known extension\n    known registry entry\n    dependencies handled\n    visible UI result\n\n\nBut other nodes can be harder.\n\nComfyUI-Copilot may involve:\n\n\n    frontend UI\n    left-panel activation\n    API/model configuration\n    Python dependencies\n    possibly conflicting packages\n\n\nActor/video/animation nodes may involve heavier dependencies such as:\n\n\n    opencv\n    onnxruntime\n    insightface\n    ffmpeg\n    torch-related packages\n    special model files\n    video models\n    face models\n    pose models\n\n\nThose are not beginner-friendly first tests.\n\nThe safe order is:\n\n\n    basic ComfyUI works\n    Manager works\n    one simple custom node works\n    one simple model works\n    then Copilot\n    then Actor/video/advanced nodes\n\n\n* * *\n\n# ComfyUI-Copilot specifically\n\nComfyUI-Copilot is probably not supposed to appear only as a normal right-click node.\n\nIts own project page describes a left-side activation button and configuration flow. So after installing it, do not only do this:\n\n\n    Right click canvas → Add Node → search \"copilot\"\n\n\nAlso check:\n\n\n    left side panel\n    extension/plugin area\n    ComfyUI startup log\n    API/model configuration step\n\n\nThere are two different possibilities:\n\nSituation | Meaning\n---|---\nCopilot failed to import | It will not appear anywhere; terminal likely says `IMPORT FAILED`\nCopilot loaded correctly | It may appear through a left-side panel button, not as a normal canvas node\n\nUseful reference:\n\n  * ComfyUI-Copilot GitHub project\n  * Example Copilot dependency/import issue\n\n\n\n* * *\n\n# Hugging Face downloads: model files are not custom nodes\n\nThis is the other big beginner trap.\n\nA Hugging Face page often hosts **model files** , not ComfyUI custom nodes.\n\nA file like this:\n\n\n    model.safetensors\n\n\ndoes not usually go here:\n\n\n    ComfyUI\\custom_nodes\n\n\nIt usually goes somewhere under:\n\n\n    ComfyUI\\models\n\n\nComfyUI model files appear in loader-node dropdowns. They do not usually create new right-click nodes.\n\n## Basic model-folder cheat sheet\n\nDownloaded file type | Usually put it here | Usually load it with\n---|---|---\nSD / SDXL checkpoint `.safetensors` or `.ckpt` | `ComfyUI\\models\\checkpoints` | `Load Checkpoint`\nLoRA `.safetensors` | `ComfyUI\\models\\loras` | `Load LoRA`\nVAE `.safetensors` | `ComfyUI\\models\\vae` | `Load VAE`\nControlNet `.safetensors` | `ComfyUI\\models\\controlnet` | `Load ControlNet Model`\nUpscaler `.pth` / `.safetensors` | `ComfyUI\\models\\upscale_models` | Upscale model loader\nText encoder / CLIP | `ComfyUI\\models\\clip` or `ComfyUI\\models\\text_encoders` | CLIP/text encoder loader\nNewer diffusion model / Flux-style model | often `ComfyUI\\models\\diffusion_models` | `Load Diffusion Model` or workflow-specific loader\nGGUF model | depends on custom node | GGUF-specific loader\nWorkflow `.json` or PNG with metadata | not a model folder | open/drag into ComfyUI\n\nOfficial and practical references:\n\n  * ComfyUI Models guide\n  * ComfyUI model troubleshooting\n  * ComfyUI LoRA tutorial\n  * Hugging Face / ComfyUI model-folder guide\n\n\n\n* * *\n\n# Hugging Face repos can contain different formats\n\nA Hugging Face repo is not always “one file for ComfyUI.”\n\nIt may contain:\n\n\n    model.safetensors\n    lora.safetensors\n    vae.safetensors\n    config.json\n    model_index.json\n    unet/\n    vae/\n    text_encoder/\n    scheduler/\n    tokenizer/\n    *.gguf\n    README.md\n    workflow.json\n\n\nIf a Hugging Face repo has folders like:\n\n\n    unet/\n    vae/\n    text_encoder/\n    scheduler/\n    model_index.json\n\n\nthat is probably a **Diffusers-style repo** , not a simple ComfyUI checkpoint.\n\nDo not just dump that whole folder into:\n\n\n    ComfyUI\\models\\checkpoints\n\n\nInstead, look for one of these:\n\n\n    ComfyUI instructions\n    a ComfyUI workflow\n    a single-file checkpoint version\n    separate ComfyUI-format weights\n    custom node instructions\n\n\nUseful Hugging Face references:\n\n  * Hugging Face: Downloading models\n  * Hugging Face Hub: Download files from the Hub\n\n\n\n* * *\n\n# Where I would start\n\nDo not start with Copilot, Actor nodes, video nodes, Flux, Wan, Qwen, GGUF, or complex Hugging Face repos.\n\nStart with one boring, known-good path.\n\n## Stage 1: make basic ComfyUI work\n\nUse the official beginner guides:\n\n  * Getting Started with AI Image Generation\n  * ComfyUI Text-to-Image Workflow\n\n\n\nYou want to understand this basic chain:\n\n\n    Load Checkpoint\n    → CLIP Text Encode positive prompt\n    → CLIP Text Encode negative prompt\n    → Empty Latent Image\n    → KSampler\n    → VAE Decode\n    → Save Image\n\n\nIf this works, ComfyUI itself is basically healthy.\n\nIf this does not work, do not debug custom nodes yet. Fix the base install, model file, GPU/Torch issue, or checkpoint path first.\n\n* * *\n\n## Stage 2: enable Manager properly\n\nFrom the portable root:\n\n\n    cd /d <ComfyUI_ROOT>\n\n    .\\python_embeded\\python.exe -m pip install -r .\\ComfyUI\\manager_requirements.txt\n\n    .\\python_embeded\\python.exe -s .\\ComfyUI\\main.py --windows-standalone-build --enable-manager\n\n\nThen add `--enable-manager` to your normal launch `.bat`.\n\nReference:\n\n  * ComfyUI Manager installation\n\n\n\n* * *\n\n## Stage 3: install one simple custom node\n\nDo not test with Copilot first.\n\nPick one simple custom node through Manager that clearly adds normal canvas nodes.\n\nInstall it.\n\nRestart ComfyUI.\n\nCheck the terminal.\n\nYou want no:\n\n\n    IMPORT FAILED\n    Traceback\n    ModuleNotFoundError\n    ImportError\n\n\nThis proves the custom-node system is working.\n\n* * *\n\n## Stage 4: test one simple Hugging Face model download\n\nStart with something simple:\n\n\n    one checkpoint\n    or\n    one LoRA\n    or\n    one VAE\n\n\nDo not start with a full Diffusers repo or a split modern model.\n\nExample folder logic:\n\n\n    checkpoint → ComfyUI\\models\\checkpoints\n    LoRA      → ComfyUI\\models\\loras\n    VAE       → ComfyUI\\models\\vae\n\n\nAfter placing the file:\n\n\n    press R in ComfyUI if appropriate\n    restart ComfyUI if needed\n    select the file in the matching loader node\n\n\nReferences:\n\n  * ComfyUI Models guide\n  * ComfyUI model troubleshooting\n  * Hugging Face download files guide\n\n\n\n* * *\n\n## Stage 5: return to ComfyUI-Copilot\n\nOnce Manager works and a simple custom node works, install Copilot cleanly.\n\nPrefer Git over ZIP if possible:\n\n\n    cd /d <ComfyUI_ROOT>\\ComfyUI\\custom_nodes\n    git clone https://github.com/AIDC-AI/ComfyUI-Copilot.git\n\n\nThen install requirements with ComfyUI’s Python:\n\n\n    cd /d <ComfyUI_ROOT>\n    .\\python_embeded\\python.exe -m pip install -r .\\ComfyUI\\custom_nodes\\ComfyUI-Copilot\\requirements.txt\n\n\nThen launch:\n\n\n    .\\python_embeded\\python.exe -s .\\ComfyUI\\main.py --windows-standalone-build --enable-manager\n\n\nThen check:\n\n\n    left side panel\n    Copilot activation button\n    startup log\n    API/model configuration prompts\n\n\nReference:\n\n  * ComfyUI-Copilot\n\n\n\n* * *\n\n# Beginner-safe diagnostic checklist\n\n## When a custom node does not appear\n\nCheck:\n\n\n    Is the folder directly under ComfyUI\\custom_nodes?\n    Is there an __init__.py file in the node folder?\n    Did I accidentally create a double-nested folder?\n    Did I install requirements with python_embeded\\python.exe -m pip?\n    Did I fully restart ComfyUI?\n    Did the terminal show IMPORT FAILED?\n    Is this node supposed to appear in the right-click menu, or somewhere else?\n\n\n## When a model does not appear\n\nCheck:\n\n\n    Is it actually a model file?\n    Is it in the right ComfyUI\\models subfolder?\n    Am I using the correct loader node?\n    Did I refresh/restart ComfyUI?\n    Is the workflow asking for an exact filename?\n    Is this model compatible with the workflow architecture?\n\n\n## When Manager does not appear\n\nCheck:\n\n\n    Did I install manager_requirements.txt?\n    Did I launch with --enable-manager?\n    Did I add --enable-manager to run_nvidia_gpu.bat?\n    Am I looking at an old guide showing an older Manager UI?\n\n\n## When `pip install` looked fine but nothing changed\n\nCheck:\n\n\n    Did I use plain pip?\n    Did I use ComfyUI’s embedded Python?\n    Did the package install into python_embeded?\n    Did the startup log still show ModuleNotFoundError?\n\n\n* * *\n\n# Good guides to read first\n\n## Core beginner ComfyUI\n\n  * Getting Started with AI Image Generation\n  * ComfyUI Text-to-Image Workflow\n  * ComfyUI Models guide\n\n\n\n## Custom nodes and Manager\n\n  * How to Install Custom Nodes in ComfyUI\n  * ComfyUI Manager installation\n  * Custom-node troubleshooting\n  * ComfyUI Wiki: install custom nodes\n\n\n\n## Models and Hugging Face\n\n  * ComfyUI model troubleshooting\n  * ComfyUI LoRA tutorial\n  * Hugging Face: Downloading models\n  * Hugging Face Hub: Download files from the Hub\n  * Hugging Face / ComfyUI model-folder guide\n\n\n\n## Copilot specifically\n\n  * ComfyUI-Copilot GitHub project\n  * Example Copilot dependency issue\n\n\n\n* * *\n\n# What I would avoid for now\n\nAvoid these until your basics are stable:\n\n\n    installing many custom nodes at once\n    using ZIP installs when Git/Manager is available\n    starting with Copilot as the first custom-node test\n    starting with Actor/video nodes\n    starting with Flux/Wan/Qwen/GGUF workflows\n    downloading entire Hugging Face repos blindly\n    putting model files in custom_nodes\n    putting custom-node code in models\n    using plain pip with Windows Portable\n\n\nThe safer beginner sequence is:\n\n\n    1. basic text-to-image workflow works\n    2. Manager works\n    3. one simple custom node works\n    4. one simple checkpoint/LoRA download works\n    5. Copilot works\n    6. Actor/video/advanced nodes work\n\n\n* * *\n\n# My final answer to “what am I doing wrong?”\n\nMost likely:\n\n  1. You are using plain `pip` instead of ComfyUI Portable’s embedded Python.\n  2. Some ZIP folders may be nested incorrectly.\n  3. Some nodes are probably failing import during startup.\n  4. You may be expecting every custom node to appear in the right-click node list.\n  5. Manager may not be enabled with `--enable-manager`.\n  6. Hugging Face model files and GitHub custom-node code are being mixed together.\n  7. ComfyUI-Copilot is not a simple first custom-node test because it uses a side-panel/configuration flow.\n\n\n\nThat is not a rare failure. It is a very common ComfyUI beginner trap.\n\nThe best way out is not more random installs. It is a clean, boring, testable path:\n\n\n    make basic ComfyUI work\n    enable Manager\n    install one simple custom node\n    install one simple model\n    then try Copilot\n    then try Actor/video nodes\n\n\nOnce that chain is stable, Hugging Face downloads and custom-node installs become much less mysterious.",
  "title": "Adding a custom_node or model"
}