HPSv3++ Model Loader

Here's the annoying part of loading a sample workflow: the author's example has a loader in it, you have no models, and half the graph is red. This node exists to fix that specific moment. It has one dropdown, one output, and it will fetch about 6.5 GB off Hugging Face the first time you press Run.

What it is

HPSv3++ Model Loader supplies the HPSV3PP_MODEL handle that HPSv3++ Score and HPSv3++ Caption require. Those two nodes won't accept anything else, and ComfyUI's socket typing means there's no clever rewiring that gets around it.

That "++" matters if you're coming in from the plain HPSv3 nodes. The pack ships two parallel series - HPSv3 and HPSv3++ - and the README states flatly that they're incompatible: connect a loader from the same series to Score and Caption. Mix them and the graph refuses to execute. If you're not sure which lineage you're in, look at the node category; HPSv3++ and HPSv3 are separate entries in the node search.

The ++ series is the one this pack is built around. The examples ship as ++ workflows (examples/caption_and_score.json, where you pick HPSv3-PlusPlus-bnb-NF4 in the loader), and the README notes that existing HPSv3++ workflows keep working as-is. If you have no existing investment and enough VRAM, start here rather than with the smaller model - same nodes, same wiring, a slightly bigger reward model behind them.

The dropdown is a download button

The model widget resolves to HPSv3-PlusPlus-bnb-NF4, and the tooltip says the useful part: it downloads automatically from Hugging Face when missing, about 6.5 GB, with progress printed to the ComfyUI console. It shows up in the list even on a machine where the model doesn't exist yet, which is deliberate - you're meant to select it and let the first run do the fetching.

bnb-NF4 means it's a merged 4-bit (bitsandbytes NF4) build. You don't need a base checkpoint or the upstream reward weights; the pack's own copy is complete. It lands at:

ComfyUI/models/hpsv3pp/HPSv3-PlusPlus-bnb-NF4/

Automatic retrieval applies to the standard model only, and the first run needs an internet connection plus roughly 6.5 GB of free space. After that, Score and Caption inference run entirely from local files - no network, no per-call anything.

Three behaviours to know, all from the README:

• A new download fetches the latest published model; existing models are not updated. To pull a newer build, move the current folder out of the way and run again.
• Cancelling mid-download is recoverable. Partial data is kept for the retry, and the model isn't used until the download and its verification finish.
• A half-placed manual model stays half-placed. If you staged the files yourself and got it wrong, the node won't patch the gap. Either add the missing pieces - config.json, reward_config.json, the tokenizer, the processor, all safetensors shards - or move the folder elsewhere and let the automatic download do it properly.

Install

Manager route: open Manager, set search type to Node Pack, search ComfyUI-HPSv3, confirm the repo is Stella2211/ComfyUI-HPSv3, install, restart ComfyUI. Manager handles the Python side - this pack wants transformers 5.17.x and bitsandbytes, and Manager also runs the pack's install.py step for you.

Manual route, from inside ComfyUI/custom_nodes:

git clone https://github.com/Stella2211/ComfyUI-HPSv3.git
cd ComfyUI-HPSv3
uv pip install --python <ComfyUI Python> -r requirements.txt
uv run --no-project --python <ComfyUI Python> python install.py

Skip the clone if Manager already installed the pack. Two copies of one custom node in custom_nodes/ is a genuinely confusing way to spend an evening.

Then verify: restart, search HPSv3++, and you should see Model Loader, Score and Caption. Load examples/caption_and_score.json, drop an image into Load Image, pick HPSv3-PlusPlus-bnb-NF4 in this node, and run it. The first run downloads the model, so go do something else.

When it goes wrong

Hardware wall. The README requires an NVIDIA CUDA GPU with BF16 support, calls 12 GB VRAM a guideline and 8 GB untested, and states that CPU, AMD and Apple GPUs are not supported. Python 3.12+ on the host, and the author tested against CUDA 13.0 - you need a driver that supports whatever PyTorch ComfyUI is carrying. This is the single most common reason someone lands here and can't make it work: the card isn't the right card.

transformers or bitsandbytes missing. Repair or reinstall the extension's dependencies in Manager and restart. Do not replace PyTorch or torchvision to fix it; the pack explicitly uses ComfyUI's own builds.

Download failure. Check internet, Hugging Face reachability, free disk and write permission on models/hpsv3pp/, then re-run the workflow and read the terminal.

Nodes never appear. The import failed. Check Manager shows the pack enabled, then look at the startup log for this extension's traceback.