JustRMBG

Offline background removal CLI powered by BRIA RMBG-2.0 (BiRefNet) running locally via ONNX Runtime. GPU-accelerated where available (DirectML on Windows, CUDA on Linux, CoreML on macOS) with automatic CPU fallback. No network access needed at runtime once the model is present — and if it isn't, it's fetched automatically.

Setup

Requires Bun 1.3+.

bun install
bun link        # registers the global `rmbg` and `justrmbg` commands

The ~1 GB ONNX model is downloaded and extracted automatically from https://m.justgains.com/tools/rmbg-2.0.zip on first run. To fetch it ahead of time instead:

bun run download-model

Usage

rmbg and justrmbg are the same command — both work from any directory.

rmbg photo.jpg                   # writes photo-nobg.png next to the input
rmbg photo.jpg -o cutout.png     # explicit output path
rmbg a.jpg b.png c.webp          # multiple images — model loads once
rmbg ./frames -o ./cutouts       # batch: every image in a folder -> <outputDir>/<name>.png
rmbg photo.jpg --cpu             # force CPU
rmbg photo.jpg --gpu             # force GPU (errors if GPU init fails)
rmbg photo.jpg --model D:\models\other.onnx

Output is always PNG with a proper alpha channel (an existing alpha channel is preserved and multiplied with the predicted matte).

Device selection

With no device flag, GPU support is autodetected: the platform's GPU providers are tried first and CPU is used if none initialize. If a GPU session initializes but later fails at inference time (flaky driver, out of VRAM), rmbg transparently recreates the session on CPU and retries.

Piping

When stdout is piped, rmbg prints one produced file path per line (all status goes to stderr), so it composes with path-consuming tools:

rmbg photo.jpg | justwebp        # remove background, then convert the cutout to WebP

Batch mode notes

In folder mode a bad file (unreadable/unsupported) is reported and skipped; the exit code is 1 only if every file fails.

Configuration

Environment variable	Effect
RMBG_MODEL	Path to the ONNX model (same as --model)
RMBG_GPU_PROVIDERS	Comma-separated GPU providers to try in auto/gpu mode (e.g. cuda,dml)

How it works

1. The image is EXIF-rotated, resized to 1024×1024, and normalized with ImageNet statistics (per the model's preprocessor_config.json).
2. The ONNX session runs with the first available execution provider: dml/cuda/coreml → cpu.
3. The predicted alpha matte is resized back to the original dimensions and multiplied into the image's alpha channel.

Performance

Measured on an RTX 4090 (DirectML), 360×450 input:

	Model load	Per image
GPU (DirectML)	~6 s	~1.4 s (first), ~0.3 s (warm)
CPU	~8 s	~18 s

Used by

JustGains-API (dev) shells out to justrmbg for exercise-thumbnail background removal when the command is available, falling back to its Python/Hugging Face pipeline otherwise (ExerciseThumbnailImageProcessor.RunBackgroundRemovalPipeline). Both use the same file→file and folder→folder contract. Override the executable it uses with JUSTGAINS_JUSTRMBG_EXE.

License note

RMBG-2.0 weights are released by BRIA under a source-available license that permits non-commercial use only. For commercial use, obtain a license from BRIA.