How to batch remove backgrounds from the command line

The bgcut CLI accepts more than one file or a directory. Batch work runs sequentially and reuses one runtime instead of starting a new inference process for every image.

Published 2026-09-29

Start with one file

The smallest CLI command takes an image path and writes a transparent PNG next to the source file unless you provide another output.

Supported inputs are JPEG, PNG, WebP, and AVIF. The first run may need to obtain and validate the model before inference can start.

npx bgcut photo.jpg

# choose an output
npx bgcut photo.jpg -o portrait.png

Pass several files to one batch

List several source files in the same command when you want them processed by one bgcut run. The CLI keeps one runtime and processes the images in order.

Sequential processing avoids pretending that every machine can run several copies of the model at once. It also makes output and failure reporting easier to follow in shell workflows.

npx bgcut first.jpg second.png third.webp

Process a directory recursively

A directory input tells bgcut to scan supported images recursively. With an output directory, the results go under that destination instead of beside each source.

Use this for photo folders, build jobs, or other file-based automation where a browser queue would add unnecessary work.

npx bgcut photos/
npx bgcut photos/ -o ./cutouts

Choose output and engine constraints

PNG is the default transparent output. Use the WebP option for lossless WebP with transparency. JPEG output uses a white background because JPEG does not carry an alpha channel.

Automatic engine selection tries native WebGPU and can use CPU if runtime creation fails. If your automation requires one engine, pass the explicit GPU or CPU option and treat failure as a real failure instead of changing the requirement.

npx bgcut photo.jpg --webp
npx bgcut photo.jpg --gpu
npx bgcut photo.jpg --cpu