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.

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

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

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

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:

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

Model

The withoutBG Open Weights Model is an ONNX bundle hosted at withoutbg/withoutbg-openweights-onnx (version 10.8.0; 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). 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)