rmbg-cli

rmbg removes image backgrounds locally with briaai/RMBG-2.0. A small Rust CLI validates arguments and starts a locked, uv-managed Transformers runtime. No hosted inference API is used.

Important

The RMBG-2.0 model weights are available for non-commercial use only under CC BY-NC 4.0. Commercial use requires a separate agreement with BRIA. The repository code remains MIT-licensed; that license does not extend to the model weights.

Example

The example below was processed locally with:

rmbg marin.png -o marin-no-bg.png

Before	After — transparent PNG

System requirements

BRIA publishes RMBG-2.0 as a 0.2B-parameter model with FP32 weights and a 1024×1024 inference size, but does not publish minimum RAM or VRAM figures. The values below are conservative project guidance based on that architecture, the 844 MB pinned weights, and the local PyTorch runtime. See the official model card and BRIA repository.

Resource	Minimum	Recommended
Platform	Linux glibc x64/ARM64, Apple Silicon macOS, or Windows x64	A current release of one of the supported operating systems
CPU	2 cores; CPU-only inference is supported	4 or more modern CPU cores
Memory	8 GB RAM	16 GB RAM
Free storage	5 GB for dependencies, weights, and caches	10 GB, especially for Linux CUDA packages
Acceleration	None; a GPU is optional	NVIDIA GPU with 6 GB VRAM, or Apple Silicon with 16 GB unified memory
Network	Required during initial setup	Broadband connection for the model and dependency download
Account	Hugging Face account with the RMBG-2.0 terms accepted	HF_TOKEN configured for non-interactive setup
Software	Python 3.10–3.12, managed by bundled uv	Node.js 18+ for npm installation; source builds may use RMBG_UV_BIN or uv from PATH; Rust 1.85+ only when building from source

The official implementation depends on PyTorch, Torchvision, Pillow, Kornia, and Transformers. CUDA, Apple MPS, and CPU execution are selected automatically by this CLI.

Installation

Install the native CLI from npm:

npm install --global rmbg2-cli
rmbg setup

Node.js is only used by the npm launcher. The image processing runtime remains local Python, Transformers, and PyTorch managed by uv.

To install without Node.js on Linux or macOS:

curl --proto '=https' --tlsv1.2 -LsSf https://github.com/shayyz-code/rmbg-cli/releases/latest/download/rmbg-installer.sh | sh

On Windows PowerShell:

irm https://github.com/shayyz-code/rmbg-cli/releases/latest/download/rmbg-installer.ps1 | iex

Both direct installers verify the downloaded archive against the release SHA-256 manifest, install into a user-local bin directory, and print PATH guidance when needed. Set RMBG_INSTALL_DIR to choose another directory or RMBG_VERSION to install a specific release.

Then prepare the local model runtime once:

rmbg setup

To build from source instead:

git clone https://github.com/shayyz-code/rmbg-cli.git
cd rmbg-cli
cargo build --release
./target/release/rmbg setup

Native distributions include pinned official uv 0.11.26. Runtime discovery uses RMBG_UV_BIN, then adjacent bundled uv, then uv from PATH. Setup installs the locked Python dependencies, starts Hugging Face login when needed, downloads the pinned 844 MB model, and validates that it loads on the selected device. If BRIA's non-commercial terms have not been accepted, setup prints the model page and can be rerun after access is granted. You can use HF_TOKEN instead of interactive login.

Setup is idempotent and reuses installed dependencies and cached weights:

rmbg setup --device cpu

Usage

Remove a background and write <input>-no-bg.png:

rmbg photo.jpg
rmbg photo.jpg -o cutout.png -v

Existing outputs are refused by default. Use --force to atomically replace one after successful processing:

rmbg photo.jpg -o cutout.png --force

Composite the foreground onto a solid color:

rmbg photo.jpg --background white -o on-white.png
rmbg photo.jpg --background "#336699" -o on-blue.png
rmbg photo.jpg --background 255,128,0 -o on-orange.png

Device selection defaults to CUDA, then Apple MPS, then CPU. Override it when needed:

rmbg photo.jpg --device cpu

Interactive terminals show a bordered five-milestone determinate progress bar. Redirected stderr prints one deterministic line per completed milestone and never emits cursor controls. Expensive stages remain at their last real percentage until the underlying work completes.

Flag	Description
-o, --output <PATH>	Output PNG path (default: <input>-no-bg.png)
--force	Atomically replace an existing output
--background <COLOR>	Solid background (#RRGGBB, R,G,B, white, black)
--device <DEVICE>	auto, cuda, mps, or cpu (default: auto)
-v, --verbose	Print model, device, revision, and output details
--quiet	Suppress progress, success, and informational output
--json	Emit one JSON result on stdout and suppress human output
--color <WHEN>	auto, always, or never (default: auto)
-h, --help	Show help

Color is enabled automatically for supported terminals and can also be controlled with NO_COLOR, CLICOLOR, and CLICOLOR_FORCE. Animation is restricted to interactive stderr even when color is forced.

--quiet and --verbose conflict, as do --json and --verbose. JSON mode disables color and animation and captures all uv, Python, and Hugging Face diagnostics. Errors use usage, user, or runtime kinds with exit code 1 or 2.

rmbg setup [--device auto|cuda|mps|cpu] [--color auto|always|never] prepares and validates all local runtime prerequisites. Because setup is reserved as a command, process a file with that exact name as rmbg ./setup.

rmbg doctor [--deep] performs read-only checks for uv, runtime files, the Python environment, local Hugging Face credentials, the exact pinned model cache, devices, automatic device selection, and at least 5 GiB of free cache storage. --deep loads only the already-cached model and never downloads it. Doctor never syncs dependencies, authenticates, accepts terms, or materializes runtime files. A file named doctor must be passed as rmbg ./doctor.

Exit code 1 indicates invalid input or a setup action the user must complete, such as installing uv, authenticating non-interactively, or accepting model terms. Exit code 2 indicates dependency, network, runtime, model-load, inference, or output failure.

How it works

The worker follows the RMBG-2.0 model card: it normalizes a 1024×1024 RGB copy, runs local Transformers/PyTorch inference, resizes the predicted grayscale matte to the original dimensions, and applies it as alpha. Existing alpha is multiplied with the prediction so transparent source pixels are never restored.

The model requires trust_remote_code=True. The tested model revision is 5df4c9c76d8170882c34f6986e848ee07fd0ba43, reported by rmbg -v. It can be overridden for deliberate maintenance with RMBG_MODEL_REVISION.

Development

uv sync --project runtime --frozen
cargo fmt --all -- --check
cargo clippy --all-targets -- -D warnings
cargo test --all
npm run check:versions
npm test
uv run --project runtime --frozen python runtime/tests/test_runtime.py

Ordinary tests use a fake segmentation model and do not download weights.

License

Repository code is MIT-licensed. RMBG-2.0 model weights are separately licensed for non-commercial use under CC BY-NC 4.0. See LICENSE and the official model card.