TBG SAM3 Model Loader and Downloader

TBG SAM3 Model Loader and Downloader is the grown-up version of the pack's simple loader. Same single SAM3_MODEL output, but instead of silently stuffing the checkpoint into your Hugging Face cache, it gives you a choice of where the weights come from - including an option that downloads sam3.pt straight into ComfyUI/models/sam3 and reuses it every session. That one line in the README - "unified model folder with other SAM3 nodes" - is the whole point of this node.

What it actually is

SAM3's image checkpoint lives in a gated Hugging Face repo, and "gated" is the operative word: you need an approved access request and a token before any downloader in this pack works. The advanced loader is the pack's answer to the two ways that can go wrong - you don't have the file locally, or you want it somewhere you can actually see and share with other SAM3 tooling. It uses huggingface_hub to fetch the checkpoint and either hand it to the model builder from the HF cache or park a copy in your ComfyUI models folder.

The two inputs (yes, two)

• model_source - the dropdown that makes this node worth having:
  • local (auto-download) (the default) - fetches sam3.pt from facebook/sam3 into ComfyUI/models/sam3/sam3.pt if it isn't already there, then loads from that path. This is the "unified model folder" mode, and it's what you want if you're also running other SAM3 packs or plan to copy the checkpoint to another machine.
  • auto (API to cache) - builds the default SAM3 model and lets the weights live in the HF cache, exactly like the simple loader does. Less visible, but zero extra disk management.
  • Any extra checkpoint files you drop into models/sam3 (.pt, .pth, .safetensors, .bin) appear here as their own choices, so this is also the loader to use if you've grabbed a custom or converted SAM3 checkpoint.
• device - cuda or cpu. Same story as everywhere else in the pack: GPU default, CPU works but is slow.

Output is the pack's internal SAM3_MODEL bundle, which feeds TBG SAM3 Segmentation and TBG SAM3 Batch Selector. Same type as the simple loader produces, so swap them freely in a workflow.

Installing and the token dance

Install the pack with ComfyUI Manager (search "TBG-SAM3") or:

cd ComfyUI/custom_nodes
git clone https://github.com/Ltamann/ComfyUI-TBG-SAM3
cd ComfyUI-TBG-SAM3
pip install -r requirements.txt

Then the actual requirement - request access at huggingface.co/facebook/sam3, wait for approval (the README quotes up to 24 hours), create a read token, and expose it before ComfyUI starts:

export HF_TOKEN="your_token"   # Linux/macOS
set HF_TOKEN=your_token        # Windows cmd

If you'd rather skip the downloader entirely, you can manually drop sam3.pt into models/sam3 yourself - the loader detects it and uses it. The README lists that as a supported alternative, and it's a reasonable escape hatch if HF_TOKEN is a pain in your setup.

Where people get burned

• The 401. Most "downloader doesn't work" reports trace back to a missing or unapproved token, not the node. The access request is the real gate.
• Half-installed sam3. The pack's install.py clones facebookresearch/sam3 and installs it editable with --no-deps; if the loader errors at build time, run python install.py in the pack folder. The pack's startup log tells you loudly when the sam3 package is missing.
• Confusing the two loaders. If you don't care where the checkpoint lives, the simple loader is fine. Reach for this one when you want the file on disk where you can see it, reuse it across packs, or point it at a custom checkpoint.

The name overpromises slightly - it can't conjure the model from nothing, and the API still has to approve you. But once you're through the gate, this is the loader that puts the model where you want it instead of where the cache decided to hide it.