rmbg-webgpu

A lightweight JavaScript background removal library powered by U²-Netp or BiRefNet and WebGPU, with WASM fallback for browsers without WebGPU support.

Install

npm install @planby-tech/rmbg-webgpu

Usage

import { removeBackground } from "@planby-tech/rmbg-webgpu";

const file = document.querySelector("input[type=file]").files[0];
const pngBlob = await removeBackground(file);

const url = URL.createObjectURL(pngBlob);
document.querySelector("img").src = url;

Reuse a session when processing more than one image:

import { RmbgSession } from "@planby-tech/rmbg-webgpu";

const session = await RmbgSession.create();

try {
  const result = await session.remove(file, {
    backgroundColor: [255, 255, 255, 255],
  });

  console.log(result.outputBlob, result.maskBlob, result.executionProvider);
} finally {
  await session.dispose();
}

API

• RmbgSession.create(options?)
• session.predictMask(source)
• session.remove(source, options?)
• removeBackground(source, options?)
• removeBackgroundData(source, options?)
• isWebGpuAvailable()

Supported input sources:

• File / Blob
• ImageData
• HTMLImageElement
• HTMLCanvasElement
• ImageBitmap
• image URL string

Model

The default bundled model is u2netp.onnx. It is small enough to ship with the package and remains the default:

If your bundler or deployment setup needs a custom model URL, pass it explicitly:

const session = await RmbgSession.create({
  model: "u2netp",
  modelUrl: "/models/u2netp.onnx",
});

In Vite-style bundlers you can also ask the app bundler to copy the packaged model asset:

import { RmbgSession } from "@planby-tech/rmbg-webgpu";
import modelUrl from "@planby-tech/rmbg-webgpu/models/u2netp.onnx?url";

const session = await RmbgSession.create({ modelUrl });

BiRefNet is also supported as an optional preset:

import { RmbgSession } from "@planby-tech/rmbg-webgpu";

const session = await RmbgSession.create({
  model: "birefnet",
});

The BiRefNet preset uses the ONNX Community model URL by default:

import { DEFAULT_BIREFNET_MODEL_URL, RmbgSession } from "@planby-tech/rmbg-webgpu";

const session = await RmbgSession.create({
  model: "birefnet",
  modelUrl: DEFAULT_BIREFNET_MODEL_URL,
});

For production apps, prefer hosting the BiRefNet ONNX file yourself and passing that URL as modelUrl. The default BiRefNet ONNX model is much larger than U²-Netp and is not bundled in this package.

Some browser/GPU combinations cannot run every BiRefNet WebGPU shader because of device storage-buffer limits. The library retries with WASM automatically when WebGPU inference fails and WASM is listed in executionProviders. You can also force WASM explicitly:

const session = await RmbgSession.create({
  model: "birefnet",
  executionProviders: ["wasm"],
});

Browser Runtime

WebGPU requires a secure context, such as HTTPS or localhost. If WebGPU is unavailable, the library falls back to the ONNX Runtime Web WASM execution provider.

License

This package is distributed under MIT AND Apache-2.0.

• Library source code: MIT. See LICENSE.
• Bundled models/u2netp.onnx: Apache License 2.0 via the U-2-Net project. See LICENSES/Apache-2.0.txt and THIRD_PARTY_NOTICES.md.
• Optional BiRefNet ONNX model: MIT via the BiRefNet and ONNX Community model repositories. The model is not bundled in this package.

Development

npm install
npm run download-model
npm run build