HPSv3 Model Loader

You dropped an HPSv3 Score node on the canvas and now there's a red socket complaining that it wants an HPSV3_MODEL. This is the node that gives you one. It has a single widget and a single output, which makes it look like it does nothing - in practice it's the thing that fetches 5.9 GB from Hugging Face the first time you hit Run.

What it's actually for

HPSv3 is a human-preference reward model: an image goes in, a score comes out. It isn't a diffusion checkpoint, so it doesn't go in models/checkpoints/, and it isn't a CLIP or VAE, so it doesn't go in the usual loader folders either. The pack gives it its own type - HPSV3_MODEL - and only two nodes in the whole ecosystem accept that socket: HPSv3 Score and HPSv3 Caption. The loader is how you satisfy them.

That type separation is worth internalising early. ComfyUI enforces socket types, so an HPSV3_MODEL output physically will not connect to a KSampler, and - the part that bites people - an HPSv3 loader will not feed an HPSv3++ node. Same pack, two incompatible series.

The widget, and why there's nothing to choose

The model dropdown resolves to HPSv3-bnb-NF4. That's it, one entry. The author's own tooltip says the rest: it "downloads automatically from Hugging Face when missing (about 5.9 GB)" and "download progress appears in the ComfyUI console."

So the dropdown isn't really a menu, it's a registry key. The -bnb-NF4 in the name means this is a 4-bit (bitsandbytes NF4) quantised build, already merged and packaged. You do not need the base model, and you do not need the original reward checkpoint sitting next to it - that's the README's explicit promise, and it's the main reason this is a one-node setup instead of the usual "download three files and hope the paths line up" ritual.

It lands at:

ComfyUI/models/hpsv3/HPSv3-bnb-NF4/

If you ever place it by hand - an offline box, or a proxy that won't let ComfyUI reach out - you need the whole directory, not just the weights: config.json, reward_config.json, the tokenizer, the processor, and every safetensors shard. A model folder that's missing the processor will be reported as incomplete, and the README is blunt that existing incomplete folders are not repaired automatically. Move it aside and let the node re-download, or add the missing files yourself.

The loader itself is cheap - it resolves a path and emits a handle. The weights get pulled into VRAM later, when a Score or Caption node actually asks for them, which is why the first run after a ComfyUI restart feels like a hang and the second one doesn't.

How to install it

Through Manager: open Manager, set the search type to Node Pack, search ComfyUI-HPSv3, confirm the repo is Stella2211/ComfyUI-HPSv3, install, restart. If it doesn't show up, search hpsv3 and clear any "Installed" filter. Manager also pulls in the Python dependencies (this pack wants transformers 5.17.x and bitsandbytes) and handles the install.py setup step for you.

Manually:

cd 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

That last line is only for manual installs. Don't clone the pack a second time if Manager already installed it - two copies of the same custom node is its own class of weird.

Hard requirements from the README, and they're not negotiable: an NVIDIA CUDA GPU with BF16 support, with 12 GB of VRAM as the guideline (8 GB "may work, but this is untested"), Python 3.12+, and a driver that supports ComfyUI's PyTorch/CUDA - the author tested on CUDA 13.0. CPU, AMD and Apple GPUs are not supported. If you're on a Mac or an older AMD card, this pack is a dead end no matter how nicely the graph is wired.

When it goes wrong

transformers or bitsandbytes not found. Repair or reinstall this extension's dependencies in Manager, then restart. Do not let anything swap out PyTorch or torchvision to "fix" it - the pack deliberately uses ComfyUI's own builds.

The download fails or stalls. Check internet, access to Hugging Face, free disk, and write permission on the destination, then just run the workflow again. Progress and errors go to the ComfyUI terminal, not the browser.

CUDA or GPU memory errors. Close whatever else is holding the card. The 5.9 GB file plus the activations of a VL-style model is a real footprint; 12 GB is comfortable, 8 GB is a gamble.

Nodes missing after restart. Confirm the pack is enabled in Manager and grep the startup log for errors from this extension. If it errored on import, the nodes simply never register.