snipbg

Remove image backgrounds locally with pretrained ONNX segmentation models (U²-Net, IS-Net, BiRefNet). Use it as a Python library, a command line tool, or a self-hosted HTTP API. One name everywhere: pip install snipbg, import snipbg, run snipbg.

pip install snipbg
snipbg remove photo.jpg          # -> photo_nobg.png

from snipbg import remove

with open("photo.jpg", "rb") as fh:
    png = remove(fh.read())

• Small dependency set: numpy, Pillow and onnxruntime. No rembg, no PyTorch.
• Runs offline after the first download. Weights are SHA-256 checked and cached.
• Same type in, same type out: bytes, file paths, PIL images and numpy arrays.
• API you can deploy: FastAPI server with an SSRF-safe URL route, a bounded worker pool and a Docker image with the weights baked in.

Contents

• Install
• Command line
• Python library
• HTTP API
• Models
• Docker
• Configuration
• How it works
• Development
• License

Install

Python 3.10 or newer.

pip install snipbg            # library + CLI
pip install "snipbg[api]"     # also the HTTP API

With uv:

uv add snipbg                              # add to a uv project
uv add "snipbg[api]"
uvx snipbg remove photo.jpg                # run the CLI without installing it
uvx --from "snipbg[api]" snipbg serve      # run the API without installing it

Model weights are downloaded the first time a model is used and cached in ~/.cache/snipbg. Set SNIPBG_HOME to cache them somewhere else.

Command line

snipbg remove photo.jpg                          # -> photo_nobg.png
snipbg remove photo.jpg -o out.png --refine --trim
snipbg remove *.jpg -o cutouts/ -m isnet-general-use
snipbg remove photo.jpg --bg white -o flat.jpg   # flat background instead of transparency
snipbg remove photo.jpg --only-mask -o mask.png
cat photo.jpg | snipbg remove - > out.png        # stdin -> stdout

snipbg models                                    # list models, show what is cached
snipbg download u2net isnet-general-use          # pre-fetch weights
snipbg download --all
snipbg download --check u2net                    # re-hash a cached file
snipbg serve --port 3001                         # run the HTTP API

snipbg remove --help lists every option. They are the same options as the library: --refine, --erode, --blur, --foreground-threshold, --background-threshold, --bg, --trim, --format and --quality.

Python library

remove() returns the type it is given:

from snipbg import remove, Remover

png_bytes = remove(jpeg_bytes)
image     = remove("photo.jpg")
array     = remove(numpy_rgb)

# Batch work: build the model session once and reuse it.
remover = Remover("isnet-general-use")
for path in paths:
    remover.remove(path, refine=True).save(path.with_suffix(".png"))

Options for remove() and Remover.remove():

Remover is lazy and thread-safe. Creating one does not touch the network or the disk. The ONNX session is built on first use and then shared across threads.

HTTP API

pip install "snipbg[api]"
snipbg serve --port 3001          # interactive docs at http://localhost:3001/docs

curl -X POST -F "image=@photo.jpg" \
  http://localhost:3001/remove-background --output out.png

curl -X POST -H "Content-Type: application/json" \
  -d '{"imageUrl": "https://example.com/photo.jpg"}' \
  http://localhost:3001/remove-background-url --output out.png

Both routes take the library's options: model, only_mask, refine, background, trim, format, quality. Send them as form fields on the upload route and as JSON keys on the URL route. Errors are always {"error": "..."} with a 4xx or 5xx status.

The URL route accepts only http and https, and the host must resolve to a public address. Each redirect hop is checked again, so a public URL cannot redirect the server to 169.254.169.254 or another private address.

Models

Picking one: start with u2net. Use u2netp when speed or size matters most, isnet-general-use for cleaner edges, and birefnet-general-lite when quality matters more than speed.

Every download is checked against the model's SHA-256. A file that does not match is thrown away instead of being cached. The weights are hosted on rembg's releases page. snipbg does its own preprocessing and postprocessing and does not depend on rembg.

Docker

docker build -t snipbg .                                  # bakes in u2net
docker build --build-arg MODELS=u2netp,silueta -t snipbg .
docker run -p 3001:3001 snipbg

The weights are downloaded in a separate build stage and copied into a slim runtime image that runs as a non-root user, so the first request does not trigger a download. If you bake in models other than the default, set SNIPBG_MODELS at run time to the same list.

Configuration

All settings are environment variables.

Library and CLI

HTTP server

The two BiRefNet models are left out of the default SNIPBG_MODELS list because they are large and use a lot of memory. Add them only on a machine with enough RAM.

How it works

input (bytes / path / PIL / numpy)
  -> images.load_image          decode to an RGB PIL image
  -> processing.preprocess      resize to the model's input, normalise, NCHW tensor
  -> onnxruntime                run the segmentation model (session.Remover)
  -> processing.postprocess     scale the mask back to the image size
  -> processing.refine_mask     optional: harden + feather the edge
  -> processing.cutout / trim / apply_background
  -> images.encode_image        same type out as came in

src/snipbg/
├── __init__.py        Public API, resolved lazily (remove, Remover, MODELS, ...)
├── models.py          Model registry: URL, SHA-256, input size, normalisation
├── download.py        Download, hash-check and cache weights (stdlib only)
├── session.py         Remover: owns the ONNX session, runs the pipeline
├── processing.py      Pure image math: preprocess, postprocess, refine, cutout, trim
├── images.py          Decode any input, encode the output
├── cli.py             `snipbg` command: remove, models, download, serve
└── server/            Optional HTTP API (the [api] extra)
    ├── app.py         FastAPI app, routes, error handling, bounded worker pool
    ├── config.py      Settings read from SNIPBG_* environment variables
    └── fetch.py       SSRF-safe image fetching for the URL route

The core library never imports server, and processing.py does no I/O, so each layer can be tested on its own.

Development

git clone https://github.com/asimmakhmudov/snipbg.git
cd snipbg
uv venv && uv pip install -e ".[dev]"     # or: python -m venv .venv && pip install -e ".[dev]"

pytest -q                     # fast: a fake ONNX session, no network
pytest -q -m model            # also runs real weights (downloads ~5 MB)
ruff check src tests && ruff format --check src tests

CI lints, runs the tests on Python 3.10–3.13, builds the package and smoke-tests the Docker image. Publishing a GitHub release uploads the package to PyPI.

Contributions are welcome. Please open an issue before starting a larger change, and make sure pytest -q and ruff pass.

License

MIT. The model weights have their own licenses, listed in the Models table.