Sapiens2 Manual Model Loader

The whole Sapiens2-Easy pack runs on one trick: a single loader that hands a task-specific Meta Sapiens2 model to whichever downstream node you plugged in. The regular Sapiens2 Model Loader does that by auto-downloading weights from Hugging Face on first use. This node, the Sapiens2 Manual Model Loader, is the variant that skips the download and points at a file you already own. Same job, no babysitting.

You reach for it when you've already pulled the official facebook/sapiens2-* checkpoints yourself, when you're working offline or air-gapped, or when you want one specific .pth file and not whatever the auto-downloader would grab. It's also the standard trick if you let the easy loader download once and then want to reuse those exact files - the pack stores everything under ComfyUI/models/sapiens2/<task>/, so the manual loader is how you turn a folder of cached weights into a controlled pipeline.

How it works

You give it a task, a checkpoint path, a model size, and a device. It loads the model into memory as a SAPIENS2_MODEL object - a bundle carrying the task, architecture, device, and dtype - and the inference nodes downstream (Sapiens2 Segmentation, Sapiens2 Normal, Sapiens2 Pointmap, Sapiens2 Pose) check that the loaded task matches theirs. The loader works for all four tasks, because under the hood it's just "load a Sapiens2 checkpoint for this task," no per-task code.

The inputs that matter

Most of the fields you can safely leave alone:

• checkpoint_path - the one you must fill in. It's a path to a local Sapiens2 checkpoint for the chosen task. Leave it empty and the node raises an error, because unlike its auto-downloading sibling, this loader cannot go fetch weights for you.
• model_size - auto (the default) infers the architecture from the checkpoint itself. Drop it to 0.4b, 0.8b, 1b, or 5b if you want to be explicit.
• device - auto, cuda, mps, or cpu. auto prefers CUDA and never silently picks MPS, because some PyTorch/MPS builds produce wrong Sapiens2 segmentation labels. Pick mps by hand only if you know your build is fine.
• detector_path - only used when task = pose. It's the local person-detector file. Leave it blank and the node falls back to a bundled RTMDet path, or ultimately to the Hugging Face DETR detector.

The output is a single model socket, which you wire straight into whichever task node you're running.

Installing it

The manual loader is one node in the Bogyie/ComfyUI-Sapiens2-Easy pack, so you install the whole pack:

cd ComfyUI/custom_nodes
git clone https://github.com/Bogyie/ComfyUI-Sapiens2-Easy.git
cd ComfyUI-Sapiens2-Easy
python install.py

Restart ComfyUI. ComfyUI Manager also has it - search "ComfyUI-Sapiens2-Easy" or "Sapiens2". The installer clones Meta's Sapiens2 source into vendor/sapiens2 and, importantly, pins your existing torch/CUDA/xformers stack with temporary pip constraints so it can't silently nuke your environment. Use python install.py --no-deps if you only want this node's direct requirements. Don't run upstream Sapiens2's requirements.txt into your ComfyUI env.

Where people get burned

The first-run model download is the real cost of this pack - these are big weights, and 5b is a lot of VRAM. Start with 0.4b or 0.8b while you build the graph, then swap to 1b for final output. And remember the manual loader is for manual setups: if you just want a working graph, the easy loader's auto-download is the friendlier default. This node is the one you graduate to when you want to know exactly which checkpoint you're running, or when the network is the enemy.

One more thing worth knowing: the pack's adapter code is MIT, but the Sapiens2 weights themselves are Meta's and governed by Meta's Sapiens2 license - check that before you ship something commercial built on the output.