ComfyUI Extension

NoBG

NoBG background removal and foreground refinement nodes for ComfyUI

By feyninc·Created 4 months ago·Updated about 20 hours ago· 172
feyninc/nobg
Nodes—
On cloudLocal install
Stars172
Updatedabout 20 hours ago
Readme
<div align="center">

nobg

<img src="https://raw.githubusercontent.com/feyninc/nobg/main/assets/nobg-logo.png" alt="nobg" width="180">

Open-source background removal & image matting

PyPI PyPI Downloads Python License

| Input | Output | |:-----:|:------:| | <img src="https://raw.githubusercontent.com/feyninc/nobg/main/assets/dog_input.png" alt="Dog in the original photo" width="320"> | <img src="https://raw.githubusercontent.com/feyninc/nobg/main/assets/dog_cutout.png" alt="Illustrative dog cutout on a transparent background" width="320"> |

</div>

Table of Contents

Installation

uv add nobg
<details> <summary>From source (with <code>uv</code>)</summary>
git clone https://github.com/feyninc/nobg.git
cd nobg
uv sync
</details>

Requires Python ≥ 3.10, torch ≥ 2.0 and torchvision ≥ 0.15. Those two are deliberately not installed for you — pick the build that matches your hardware (a CPU wheel, a CUDA one, ROCm) and install it yourself:

uv add torch torchvision

See pyproject.toml for the full dependency set.

Quick Start

Remove a background in three lines:

from nobg import AutoModel

model = AutoModel.from_pretrained("feyninc/FeyNobg")
model.process("input.jpg").save("output.png")

process handles the whole pipeline — load, preprocess, forward under no_grad in eval mode, post-process, composite — and builds the processor the model's own config implies, so there is nothing else to load. image takes anything loadimg accepts: a path, URL, base64 string, numpy array or PIL image. Pass a list to get a list back, each matte returned at its own original resolution:

for cut, path in zip(model.process(["a.jpg", "b.jpg"]), ("a.png", "b.png")):
    cut.save(path)

Useful keywords: batch_size (images per forward pass; defaults to 1 to keep peak memory flat), return_type="alpha" for the raw (H, W) matte tensors instead of RGBA cutouts, and any remaining kwargs go to the processor.

predict is the same call with the processor passed in — reach for it when you already have one, or when a checkpoint's preprocessor_config.json differs from its config.image_size (process trusts the model config):

from nobg import AutoProcessor

processor = AutoProcessor.from_pretrained("feyninc/FeyNobg")
model.predict(processor, "input.jpg").save("output.png")

The processor comes first, then the inputs that vary: predict(processor, image, prompt, boxes), each one optional after image (BiRefNet takes neither prompt nor boxes; SAM3 takes both). model.default_processor() returns the one process would build, if you want it without the Hub round-trip.

Or drive the steps yourself when you need the intermediates:

import torch
from loadimg import load_img

image = load_img("input.jpg").convert("RGB")
inputs = processor(image, return_tensors="pt")

with torch.no_grad():
    outputs = model(pixel_values=inputs["pixel_values"])

alpha = processor.post_process_alpha_matting(
    outputs, target_sizes=[(image.height, image.width)]
)[0]
processor.cutout(image, alpha).save("output.png")

Or try it in the browser first: 🤗 FeyNobg Space.

Model Zoo

| Model | Repo | Params | Resolution | Task | Notes | |:------|:-----|:------:|:----------:|:-----|:------| | FeyNobg | feyninc/FeyNobg | 0.3 B | 1024 × 1024 | Background removal / matting | Strongest published model, start here | | SAM3 | facebook/sam3 | 0.84 B | 1008 × 1008 | Background removal + text-promptable segmentation | Load with Sam3.from_origin. Picks the subject well; edges stay softer than FeyNobg. Gated; weights are under Meta's SAM License |

ComfyUI integration

The separate NoBG Comfy Registry pack is released independently of the PyPI library. The first Registry release (0.1.0) depends on a published nobg>=0.3.2 wheel containing nobg.comfyui.nodes; PyPI nobg 0.3.1 does not include the integration. The Registry release must wait until that library wheel is published.

For a published release, install the NoBG Registry pack through ComfyUI Manager and restart ComfyUI. The pack installs the nobg library but no model weights. The first Registry version (0.1.0) requires a published PyPI nobg>=0.3.2 wheel; Registry and PyPI version numbers are independent.

For development from a source checkout, use ComfyUI's Python environment (replace python below with the Python executable ComfyUI uses), install the library, then link the entrypoint and restart ComfyUI:

python -m pip install -e /path/to/nobg
ln -s /path/to/nobg/comfyui /path/to/ComfyUI/custom_nodes/nobg

The entrypoint registers NoBG Model Loader, NoBG Remove Background and NoBG Refine Foreground. In the loader, choose feyninc/FeyNobg (default) or facebook/sam3; the Hub preset downloads weights on first use and caches them. Alternatively, for offline use, put a checkpoint in ComfyUI/models/nobg/<name>/config.json and ComfyUI/models/nobg/<name>/model.safetensors, restart ComfyUI, then select local: <name>. Other ComfyUI nobg model search paths are also scanned. Local architecture is read from config.json, not guessed from the folder name. For offline SAM3, include tokenizer files in the local checkpoint directory or pre-cache the fallback openai/clip-vit-large-patch14 tokenizer while online. To use a gated upstream facebook/sam3 snapshot offline, first download its config.json and model.safetensors with approved Hub access; the upstream config/weights differ from nobg-format SAM3 checkpoints.

For facebook/sam3, request/accept access on its gated Hub page, then authenticate in ComfyUI's environment before starting ComfyUI: use hf auth login with an authorized token, or set HF_TOKEN in the process environment. The removal node has a prompt text widget: enter a description such as the dog to select a subject with SAM3, or leave it empty to use SAM3's default prompt. BiRefNet ignores prompts. SAM3 weights are subject to Meta's SAM License.

Connect Load Image → NoBG Remove Background (image) and NoBG Model Loader → NoBG Remove Background (nobg_model), then connect cutout directly to Save Image for a transparent PNG. The removal node accepts image batches and returns an RGBA cutout, RGB foreground, and a foreground alpha mask (1 = keep/opaque, 0 = background/transparent). ComfyUI's Load Image mask is inverted from alpha (1 = transparent region); invert that mask before using it as NoBG's foreground mask. For soft edges, enable refine_foreground or pass the original RGB image and NoBG mask to NoBG Refine Foreground, then save its cutout. The removal node's batch_size input processes 1–16 images per inference pass (default 1); increase it for throughput if memory allows. CPU inference and refinement can be slow. Sample workflows are in comfyui/example_workflows/. Their thumbnails preview a dog cutout, but the workflow JSON does not include that photo. After opening a template, select or upload your own image in Load Image: the referenced example.png is only a placeholder, not an included input. The SAM3 template additionally requires approved Hub access and authentication as described above. Direct Python calls to NoBGRemoveBackground.remove(...) also accept boxes and score_threshold; these are not ComfyUI inputs. The UI exposes the SAM3 text-prompt widget and batch_size input, but not visual boxes.

ComfyUI is not a dependency of the regular nobg Python package; the node module loads only through the ComfyUI entrypoint. If you already have ComfyUI-NoBG installed, remove or disable that node pack before enabling this one to avoid duplicate node names. Installing only the nobg wheel does not register nodes: ComfyUI must see custom_nodes/nobg/__init__.py.

Registry metadata, licensing, release notes and the entrypoint live in comfyui/. To release a new Registry version, increment comfyui/pyproject.toml and add a nonempty matching section to comfyui/CHANGELOG.md. Run the Publish NoBG to Comfy Registry manual workflow only after the required PyPI wheel is live. It checks lint, types, tests, the published wheel and the tracked-only snapshot and archive before publishing from comfyui/. It then reads back the Registry version changelog. If the Registry reports a pending security scan, run the same workflow with verify_only after the scan; flagged/banned versions require investigation. It uses the REGISTRY_ACCESS_TOKEN repository secret and does not invoke the root PyPI publishing workflow. comfy-cli==1.26.0 repacks the archive when publishing; Ruff runs with RUFF_NO_CACHE=true, and generated .ruff_cache/__pycache__ files are ignored by the snapshot audit (never included in its tracked-file archive). Before publishing, the workflow verifies archive members byte-for-byte against the staged snapshot; afterward, it verifies the repacked members. This does not prove the inspected ZIP's exact bytes were uploaded or rule out changes inside the CLI between repack and upload. The token is supplied through the CLI's hidden stdin prompt, not in command arguments; avoid untrusted processes on the release runner.

Usage

AutoModel & AutoProcessor

AutoModel reads the repo tags and returns the concrete class. AutoProcessor reads preprocessor_config.json (or falls back to the model config) and returns the matching image processor.

from nobg import AutoModel, AutoProcessor

model = AutoModel.from_pretrained("feyninc/FeyNobg")
processor = AutoProcessor.from_pretrained("feyninc/FeyNobg")

Concrete classes work too, if you'd rather be explicit:

from nobg import BiRefNet, BiRefNetImageProcessor

model = BiRefNet.from_pretrained("feyninc/FeyNobg")
processor = BiRefNetImageProcessor.from_pretrained("feyninc/FeyNobg")

Constructing from scratch (random init) uses the config dataclass:

from nobg import BiRefNet
from nobg.birefnet.modeling_birefnet import BiRefNetConfig

model = BiRefNet(BiRefNetConfig(image_size=512, embed_dim=128))

SAM3: text-promptable cutouts

Sam3 wraps transformers' SAM3 and exposes its prompt-conditioned segmentation as a single alpha matte, so it drops into the same flow as BiRefNet:

from nobg import Sam3

model = Sam3.from_origin("facebook/sam3")
model.process("input.jpg").save("output.png")

Because SAM3 is open-vocabulary, you can cut out specific things by passing a prompt as the second argument — this is the capability BiRefNet doesn't have:

model.process("input.jpg", "the dog").save("dog.png")

With no prompt, the processor supplies default_prompt ("the main foreground subject"), which is what makes prompt-free background removal work.

The third argument is boxes — a visual prompt, in the original image's pixel coordinates. Use it when the thing you want is easier to point at than to name:

model.process("input.jpg", None, [[120, 80, 460, 720]]).save("cutout.png")

Unlike prompt, boxes is per-image: pass [[x1, y1, x2, y2], ...] for one image, or one such list per image for a batch. Boxes and a prompt can be combined; with boxes and no prompt, SAM3 segments what the boxes point at.

images = ["a.jpg", "b.jpg"]
boxes = [[[10, 10, 200, 300]], [[40, 60, 380, 500], [400, 20, 620, 260]]]
cuts = model.process(images, "the dog", boxes)

process builds its processor from the model config: image size and default_prompt come straight from it, and the CLIP tokenizer is loaded from whatever repo from_origin read the weights from, falling back to the ungated openai/clip-vit-large-patch14 (SAM3's text tower is CLIP's). Pass tokenizer= a repo id, a directory or an instance to override that. When you'd rather hold the processor yourself, predict is the same call with it passed in first:

from nobg import Sam3Processor

processor = Sam3Processor.from_pretrained("facebook/sam3")
model.predict(processor, "input.jpg", "the dog").save("dog.png")

By default the matte comes from SAM3's own prompt-conditioned semantic head (config.aggregate="semantic"). Set aggregate to "max" or "mean" to build it from the union of per-object instance masks instead — that path respects score_threshold (how many detected objects land in the matte, falling back to the best-scoring one so the matte is never empty), but produces a noticeably softer alpha:

model = Sam3.from_origin("facebook/sam3", aggregate="max")
model.predict(processor, "input.jpg", score_threshold=0.5)

Measured against FeyNobg on two photos, the semantic head is the clear default: MAE 0.035/0.039 with 19/29 % of pixels at intermediate alpha, versus 0.144/0.150 and 71/79 % for the instance union. Reach for "max"/"mean" when you specifically want the matte to track the detected instance set.

The step-by-step form, when you want the instance-level outputs:

import torch
from loadimg import load_img

image = load_img("input.jpg").convert("RGB")
inputs = processor(images=image, text="the dog", return_tensors="pt")

with torch.no_grad():
    outputs = model(**inputs)

alpha = processor.post_process_alpha_matting(
    outputs, target_sizes=[(image.height, image.width)]
)[0]
processor.cutout(image, alpha).save("output.png")

Because the matte is never empty, a prompt for something that isn't in the image still returns one. Read presence_logits to tell the difference — SAM3's presence head is a reliable confidence signal (on a cosplay photo: "the person" → 0.97, "the hat" → 0.85, "the dog" → 0.001):

confidence = outputs["presence_logits"].sigmoid().item()

The per-object outputs come through untouched (pred_masks, pred_boxes, pred_logits, presence_logits, semantic_seg), so processor.image_processor.post_process_instance_segmentation still works for instance-level use.

Which model to reach for. SAM3 finds the right subject — on a test photo its matte agrees with FeyNobg at IoU 0.98 — but it's a detector, not a matting model: masks are predicted at a fraction of the input resolution and upsampled, so edges stay softer (19 – 29 % of pixels land at intermediate alpha, versus 3 % for FeyNobg). Use SAM3 when you need to choose what to cut out, and FeyNobg when you need hair-level edges.

[!NOTE] nobg ships no SAM weights — from_origin("facebook/sam3") downloads them from Meta's gated repo, under Meta's SAM License rather than nobg's Apache-2.0. Accept it on the Hub first. Only the Apache-2.0 transformers implementation is used in code.

Note that pixel_values must be exactly config.image_size square — the vision tower's rotary embeddings are fixed-size — so always preprocess through Sam3Processor.

Batched inference

predict takes a list and returns one result per input, each at its original resolution. batch_size sets how many go through each forward pass:

paths = ("a.jpg", "b.jpg", "c.jpg")
for cut, path in zip(model.predict(processor, list(paths), batch_size=4), paths):
    cut.save(path.replace(".jpg", ".png"))

Or drive it manually — post_process_alpha_matting takes one target size per image, so mattes come back at each original resolution:

images = [load_img(p).convert("RGB") for p in paths]
inputs = processor(images, return_tensors="pt")

with torch.no_grad():
    outputs = model(pixel_values=inputs["pixel_values"])

mattes = processor.post_process_alpha_matting(
    outputs, target_sizes=[(im.height, im.width) for im in images]
)
for im, alpha, path in zip(images, mattes, ("a.png", "b.png", "c.png")):
    processor.cutout(im, alpha).save(path)

The same pattern handles video: decode to frames, batch them, composite back.

Refining the foreground

A soft matte leaves the old background mixed into every semi-transparent pixel, so compositing the original pixels onto a new background shows a halo of the old one — most visible on hair, fur and motion blur. refine_foreground estimates the unmixed foreground color for those pixels, and cutout(refine=True) applies it in place:

processor.cutout(image, alpha, refine=True).save("output.png")

It is pure torch, so it runs wherever its inputs live — keep the tensors on the GPU and the refinement stays there too:

alpha = processor.post_process_alpha_matting(
    outputs, target_sizes=[(image.height, image.width)]
)[0]
foreground = processor.refine_foreground(pixel_tensor.cuda(), alpha.cuda())

r (default 90) sets how far the estimator reaches for a color to borrow; the cost grows about linearly with it.

GPU & half precision

model = AutoModel.from_pretrained("feyninc/FeyNobg").eval().to("cuda")
inputs = processor(image, return_tensors="pt").to("cuda")

with torch.no_grad(), torch.autocast("cuda", dtype=torch.bfloat16):
    outputs = model(pixel_values=inputs["pixel_values"])

Fine-tuning on custom data

NoBg provides the model, processor, and loss needed to train BiRefNet on your own image and mask pairs. Because the model plugs into the Hugging Face Trainer, you get its full training loop, checkpointing, and evaluation for free.

from transformers import Trainer, TrainingArguments
from nobg import AutoProcessor, AutoModel

model = AutoModel.from_pretrained("nobg/FeyNobg")
processor = AutoProcessor.from_pretrained("nobg/FeyNobg")


def collate(examples):
    batch = processor(
        images=[ex["image"] for ex in examples],
        segmentation_maps=[ex["mask"].convert("L") for ex in examples],
        return_tensors="pt",
    )
    return {"pixel_values": batch["pixel_values"], "labels": batch["labels"]}


trainer = Trainer(
    model=model,
    args=TrainingArguments(output_dir="outputs", learning_rate=2e-5),
    train_dataset=dataset,
    data_collator=collate,
)
trainer.train()
<details> <summary>Swapping the loss</summary>

model.criterion is a plain function attribute, not a submodule, so it never enters the state dict and you can replace it outright:

from nobg.loss import birefnet_loss, iou_loss, ssim_loss


def my_loss(scaled_preds, gt):
    return birefnet_loss(scaled_preds, gt) + 5 * iou_loss(
        scaled_preds[-1].sigmoid(), gt
    )


model.criterion = my_loss
</details>

Re-parameterizing a checkpoint

BiRefNet.from_origin builds a new model from an existing one, injecting every weight whose key and shape still match and freshly initializing the rest. Handy for changing resolution, growing the decoder, or migrating pre-0.2.0 checkpoints.

from nobg import BiRefNet

model = BiRefNet.from_origin("feyninc/FeyNobg", image_size=2048)

origin may be a Hub repo id, a local directory with config.json + model.safetensors, or a live nn.Module.

Push to HuggingFace Hub

model.push_to_hub("your-username/model-name")
processor.push_to_hub("your-username/model-name")

A bare name is auto-prefixed with your Hub username, and a model card is generated from the shared template.

ONNX export

Every model has an ONNX counterpart of each of those three calls. They need the extra:

uv add "nobg[onnx]"
model.onnx_save_pretrained("onnx-out")          # -> onnx-out/model.onnx + config.json + README.md
model.onnx_push_to_hub("your-username/model-name-onnx")

Loading gives back an OnnxModel — the graph under onnxruntime, with the same process, predict, default_processor and config as the torch model, so it drops into the code above unchanged:

from nobg import BiRefNet

model = BiRefNet.onnx_from_pretrained("your-username/model-name-onnx")
model.process("input.jpg").save("output.png")

providers= picks the execution provider (defaults to everything installed, so an onnxruntime-gpu build uses the GPU); session_options= takes an onnxruntime.SessionOptions.

A dedicated -onnx repo is one option; subfolder= is the other, and it is the convention optimum and transformers.js already look in. All three calls take it:

model.onnx_save_pretrained("out", subfolder="onnx")     # -> out/onnx/model.onnx + config.json
model.onnx_push_to_hub("your-username/model-name", subfolder="onnx")

model = BiRefNet.onnx_from_pretrained("your-username/model-name", subfolder="onnx")

The push is scoped with path_in_repo, so it writes onnx/ and nothing else — the model.safetensors beside it, the processor config and any eval assets are not part of the commit. The repo's model card is patched in a second, separate commit rather than regenerated: it gains the onnx tag and a "how to load the ONNX export" section if they aren't already there, so re-pushing is idempotent and a hand-written card survives. Pass update_model_card=False to leave the card alone entirely; onnx_save_pretrained takes model_card= for the same decision locally, its default being "no README.md inside a subfolder", since the directory it joins already has one.

Loading with subfolder= narrows the download to that folder plus the root metadata, so pulling a graph out of a torch repo doesn't drag the safetensors along. config.json is read from the subfolder if it's there and from the repo root otherwise, since that's where the Hub convention keeps it.

Two things differ from the torch model. Shapes are fixed at export time, batch size included — transformers' Swin windowing reshapes with Python ints, which pins the batch no matter what dynamic_axes claims, so export at the batch size you'll run at and read it back off model.batch_size:

model.onnx_save_pretrained("onnx-out", batch_size=4)

And only the matte is exported: the graph returns logits alone, without BiRefNet's intermediate_logits or SAM3's instance heads (pred_masks, presence_logits, …). Keep the torch model for those.

The graph's inputs come from onnx_dummy_inputs() — pixel_values for BiRefNet, plus input_ids/attention_mask for SAM3, whose text prompt is therefore baked in as shape only: any prompt Sam3Processor produces (it pads to 32 tokens) runs on the same graph. Pass dummy_inputs= to trace a variant, e.g. a box-promptable SAM3:

inputs = model.onnx_dummy_inputs()
inputs["input_boxes"] = torch.zeros(1, 1, 4)  # one box per image — only the shape is traced
model.onnx_save_pretrained("onnx-out", dummy_inputs=inputs)

Anything else goes to torch.onnx.export, opset_version included (the default, 19, is the floor for BiRefNet's DeformConv).

Acknowledgement

  • BiRefNet by Peng Zheng et al., the architecture and training recipe this library builds on.
  • SAM 3 by Nicolas Carion et al. (Meta AI), wrapped here through its Apache-2.0 transformers implementation — no SAM weights are redistributed.
  • transformers and huggingface_hub for the backbone, processor base and Hub integration.

Citation

@software{nobg,
  title={nobg: Open Source Background Removal Models for Image and Video Matting},
  author={Hichri, Hafedh},
  year={2026},
  url={https://github.com/feyninc/nobg},
  license={Apache-2.0},
}