Sapiens2 Model Loader

This is the boring first step of every Sapiens2 workflow, and that's a compliment. The Sapiens2 Model Loader loads one of Meta's Sapiens2 checkpoints and hands it to you as a reusable SAPIENS2_MODEL object - which then feeds a Sapiens2 Inference node. It's the only loader in the pack, and the whole starsFriday/ComfyUI-Sapiens2 install is just this node plus one inference node, so you're not staring at forty unfamiliar widgets.

What's Sapiens2 in the first place? Meta's family of high-resolution vision transformers, pretrained on a billion human images, targeting human-centric jobs: body-part segmentation, pose estimation, surface normals, and point maps. It landed in spring 2026 and a small crowd of wrappers sprouted around it - Kijai's, lassiiter's, this one. What makes this pack nice is that it's self-contained: it vendors the standalone Sapiens2 backbone, so you don't need the upstream repo sitting around. Point it at weights, done.

The input that matters: task

task decides which head gets loaded, and it changes what the whole pipeline means downstream:

• seg - 29-class human parsing (hair, hands, clothing, the works)
• pose - 308-keypoint pose estimation
• normal - surface normals as RGB
• pointmap - human-centric depth/geometry
• pretrain - feature visualization, for people who debug models for fun. Not for normal use.

That's the choice that counts. Everything else is set once and forgotten.

The rest of the inputs, in order of how often you touch them

• arch - sapiens2_0.4b (default), sapiens2_0.8b, sapiens2_1b, sapiens2_5b. Start at 0.4b. The 5B is optional, huge, and needs serious VRAM; the README says so in so many words. sapiens2_0.1b also appears in the list but it's only valid for pretrain - pick it with a real task and you'll never find a file.
• checkpoint - a dropdown populated from what's on disk under models/sapiens2/. auto matches by task + arch, so seg + 0.4b finds models/sapiens2/seg/sapiens2_0.4b_seg.safetensors. It scans the shared ComfyUI/models/sapiens2 folder, the pack's own models/ dir, and $SAPIENS_CHECKPOINT_ROOT if you set it.
• checkpoint_path - manual override. The tooltip says it: "Optional absolute/relative checkpoint path. Overrides the checkpoint dropdown when non-empty." This is your escape hatch when auto-matching misses.
• precision - auto, bf16, fp16, fp32. Auto is genuinely fine: bf16 on a GPU that supports it, fp16 otherwise, fp32 on CPU (where you're slow no matter what - the README is blunt that CPU is "for small tests only").
• device - auto, cuda, cpu. Auto uses ComfyUI's current torch device, which is what you want 99% of the time.

Outputs

Two: sapiens2_model (the SAPIENS2_MODEL object that wires straight into Sapiens2 Inference) and load_info_json, a JSON string reporting how many tensors actually matched the checkpoint. It's a diagnostic gift - if a checkpoint name is lying about what's inside, the load info is where you see it. Preview it with a Text node if things behave oddly.

Installing it

ComfyUI Manager handles it (search "ComfyUI-Sapiens2"), or do it by hand:

cd ComfyUI/custom_nodes
git clone https://github.com/starsFriday/ComfyUI-Sapiens2.git
cd ComfyUI
python -m pip install -r custom_nodes/ComfyUI-Sapiens2/requirements.txt

Dependencies are refreshingly tiny - numpy, Pillow, safetensors, huggingface_hub. The pack deliberately doesn't pin PyTorch because ComfyUI already manages that. The install hook creates the models/sapiens2/{seg,normal,pointmap,pose,pretrain} folders on first load.

Weights come from Hugging Face, and you want them before you try anything:

python custom_nodes/ComfyUI-Sapiens2/scripts/download_models.py --arches 0.4b

That grabs the smallest sensible set. If HF is crawling for you, the pack ships an hfd.sh script instead. Restart ComfyUI and the node appears as "Sapiens2 Model Loader".

When it fights back

• "checkpoint not found" - the file isn't under the right task subfolder (models/sapiens2/seg/, not loose in models/sapiens2/), or you picked 0.1b with a real task. When in doubt, paste the full path into checkpoint_path.
• CUDA out of memory - you're on 5B, or a big batch. Drop to 0.4b first.
• A load-time error about scaled_dot_product_attention - the source raises if your torch is too old for it. Update torch via ComfyUI's normal update path.

One honest take: for a first run, task=seg, arch=0.4b, everything else auto. If it works, then go chasing 5B and fancy precision. If it doesn't, it's almost never the settings.