withoutbg-python

withoutBG

Remove backgrounds in Python. Free locally. One line to switch to the Cloud API.

Same API for both paths: run open weights on your machine (private, offline, unlimited) or call the Cloud API (sharper edges on hair and fur, no local GPU). Built for scripts, notebooks, backends, and batch jobs.

Full documentation →

See the results

Open Weights results → · Cloud API results → · Compare →

Three lines of Python

from withoutbg import WithoutBG

model = WithoutBG.open_weights()
model.remove_background("photo.jpg").save("result.png")

Returns a PIL Image in RGBA. Prefer PNG or WebP; JPEG drops transparency silently.

Smart brush: fix it with two strokes (new in 1.4)

Missed a strand? Kept a chair you didn't want? Paint over it. Smart brush takes two masks (white = painted) and fixes the cutout locally with a 2.5 MB stroke-edit network. One stroke on an object reaches the whole object; everything away from your strokes stays as it was.

from withoutbg import WithoutBG

model = WithoutBG.open_weights()
result = model.remove_background("photo.jpg")
fixed = model.edit("photo.jpg", remove="remove.png", keep="keep.png", matte=result)
fixed.save("fixed.png")

Masks can be file paths, bytes, PIL images or NumPy arrays (bool or 0..1 floats) at the photo's size. Pass the last result as matte to keep refining in rounds. Where Keep and Remove overlap, Remove wins.

On withoutBG's frozen validation set, one round of strokes cuts the error inside the edited region by 83 % on matte fixes and by 96 % on unwanted / missing objects.

Smart brush with the withoutBG API

The API takes the same strokes. It re-mattes the photo on every call, so send all strokes so far each time. It keeps no state between calls (no matte or context to store), and each call costs 1 credit. There is no matte argument.

from withoutbg import WithoutBG

model = WithoutBG.api(api_key="sk_...")
fixed = model.edit("photo.jpg", keep="keep.png", remove="remove.png")
fixed.save("fixed.png")

From the CLI: withoutbg photo.jpg --use-api --remove remove.png --keep keep.png.

Install

uv add withoutbg

Don't have uv yet? It's a fast Python package manager from Astral. Install it once, then the command above.

Quick start

Local (Open Weights: free, private, offline):

from withoutbg import WithoutBG

model = WithoutBG.open_weights()
result = model.remove_background("input.jpg")
result.save("output.png")

First local run downloads ~1.5 GB of weights from Hugging Face (once; the BiRefNet branch is fetched the first time an image needs it). After that, everything stays on your machine.

Cloud (withoutBG API: best quality):

from withoutbg import WithoutBG

# Pass api_key here, or set WITHOUTBG_API_KEY in the environment
model = WithoutBG.api(api_key="sk_your_key")
result = model.remove_background("input.jpg")
result.save("output.png")

Batch (load once, process many):

from withoutbg import WithoutBG

model = WithoutBG.open_weights()  # keep this object alive

images = ["photo1.jpg", "photo2.jpg", "photo3.jpg"]
results = model.remove_background_batch(images, output_dir="results/")

Recreating the model for every image reloads the weights each time. Don't do that in a loop.

Progress callback:

def on_progress(value: float) -> None:
    print(f"{value * 100:.0f}%")

result = model.remove_background("photo.jpg", progress_callback=on_progress)

Runnable scripts live in examples/.

Choose your mode

	Local (open_weights())	Cloud (api())
Cost	Free forever	Pay per image
Quality	Good	Better (esp. hair, fur)
Privacy	Stays on your machine	Image sent to API
GPU required	No (CPU ONNX)	No
First-run setup	~1.5 GB download, once	API key only
Best for	Offline, private, batch jobs	Products, occasional use

Need offline or private processing?   → Local
Processing a large batch?             → Local (pay setup once, amortize across images)
Building a product?                   → Cloud (better quality, zero infra)
Occasional use, no setup tolerance?   → Cloud

CLI

# Single image (local model)
withoutbg photo.jpg
withoutbg photo.jpg --output result.png

# Cloud API
export WITHOUTBG_API_KEY=sk_your_key
withoutbg photo.jpg --use-api

# JPEG with white background fill
withoutbg portrait.jpg --format jpg --quality 95

# Smart brush: fix a cutout with masks (white = painted)
withoutbg photo.jpg --remove remove.png --keep keep.png
withoutbg photo.jpg --remove more.png --matte photo-withoutbg.png -o photo-v2.png

withoutbg --help

What you get

All methods return a PIL Image in RGBA mode:

result = model.remove_background("photo.jpg")

result.save("output.png")   # keeps transparency
result.save("output.webp")  # keeps transparency
result.save("output.jpg")   # transparency dropped silently

Compositing example:

from PIL import Image
from withoutbg import WithoutBG

model = WithoutBG.open_weights()
fg = model.remove_background("subject.jpg")
bg = Image.open("background.jpg")
bg.paste(fg, (0, 0), fg)  # alpha used as mask
bg.save("composite.png")

Configuration

Environment variable	Effect
WITHOUTBG_API_KEY	API key for Cloud mode (alternative to api_key=)
WITHOUTBG_MODEL_PATH	Path to a local .onnx file (skips Hugging Face download)

When using WITHOUTBG_MODEL_PATH, keep the sidecar metadata file (withoutbg-open-weights.onnx.json) next to the ONNX file.

Error handling

from withoutbg import WithoutBG, APIError, WithoutBGError

try:
    model = WithoutBG.api()
    result = model.remove_background("photo.jpg")
    result.save("output.png")
except APIError as e:
    print(f"API error: {e}")
except WithoutBGError as e:
    print(f"Processing error: {e}")

Troubleshooting

Model download fails: Weights come from Hugging Face on first local run (~1.5 GB). Check your connection, or set WITHOUTBG_MODEL_PATH to a local copy.

Import error:

which python
uv pip list | grep withoutbg
uv add withoutbg

API key rejected: Get a key at withoutbg.com. Set export WITHOUTBG_API_KEY=sk_your_key.

Migrating from older names (WithoutBG.opensource(), ProAPI): see docs/MIGRATION.md.

More than Python

This package is the in-process path: embed withoutBG in your Python code or CLI. Same open-weights technology powers the rest of the ecosystem; pick the surface that matches your workflow:

Surface	Choose when
Docker / self-host	You want an HTTP API or browser UI on your own server (CPU or NVIDIA GPU)
Mac app	You want a native desktop cutout tool, with an optional Local API for plugins and scripts
GIMP plugin	You edit in GIMP 3 and want a private, mask-first workflow via Mac Local API or Docker
Hugging Face · Space	You want to try a demo or download the ONNX weights directly
Cloud API	You need maximum quality without running inference yourself

# Self-host the open-weights web app (CPU)
docker run --rm -p 8080:8080 withoutbg/withoutbg-openweights-v4-app-cpu

Model

The withoutBG Open Weights Model is an ONNX bundle hosted at withoutbg/withoutbg-openweights-onnx (version 10.12.4, Open Weights v4; the SDK pins the Hub revision). Built with DINOv3.

A trained router looks at each image and picks a branch:

• Fine strands, soft detail, transparency → the withoutBG matting model (Depth Anything V2 small depth + DINOv3 ConvNeXt-fused matting), trained and maintained by withoutBG.
• Hard opaque objects, flat scenes, vehicles → BiRefNet segmentation.

Only the selected branch runs, and its alpha is upsampled to the image's native resolution (up to 4096 px per side). edit() adds the Smart brush stroke-edit graph on top. To run offline, download the whole bundle and set WITHOUTBG_MODEL_PATH to withoutbg-open-weights.onnx inside it; the other graphs are read from the same folder.

Licensed under the withoutBG Open Model License (Apache 2.0 for withoutBG portions; Meta DINOv3 License for DINOv3 backbone weights; MIT for BiRefNet). See the model's LICENSE.

Development

uv sync --extra dev

make test-fast    # fast unit tests
make quality      # lint + format + type check
make test         # full suite (downloads model on first run)

See CONTRIBUTING.md for the full guide.

License

This Python SDK is licensed under Apache License 2.0. See LICENSE.

The withoutBG Open Weights Model is a composite artifact with additional terms for embedded DINOv3 weights. See the withoutBG Open Model License, LICENSE-DINOv3, and NOTICE.

Third-party components

• DINOv3 (Meta): Meta DINOv3 License (backbone weights in the Open Weights Model)
• Depth Anything V2: Apache 2.0 (small variant; only the small variant is permissive)
• BiRefNet (ZhengPeng7): MIT (segmentation branch of the Open Weights Model)

See THIRD_PARTY_LICENSES.md for complete attribution.

Support

• Bugs / questions: GitHub Issues
• Commercial: [email protected]
• Security: [email protected] (see SECURITY.md)