Skip to main content

withoutBG

withoutBG Intro

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

PyPI License CI

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

Example 1 Example 2 Example 3

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.

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

Metadata

Release files for withoutbg 1.5.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for withoutbg 1.5.0
File Size Uploaded Provenance Actions
withoutbg-1.5.0.tar.gz 310.5 kB With provenance Details for withoutbg-1.5.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for withoutbg 1.5.0
File Interpreter ABI Platform Actions
withoutbg-1.5.0-py3-none-any.whl Python 3 none any Details for withoutbg-1.5.0-py3-none-any.whl

Total release size: 348.7 kB

Release files / withoutbg-1.5.0.tar.gz

Download URL withoutbg-1.5.0.tar.gz
Size 310.5 kB
Tags Source
SHA-256 checksum
How to use checksums
0ee34f6f16fc9a670eff335cd0f1d2ae43bdedc38f3e706918fd130870f10c34
BLAKE2b-256 checksum
How to use checksums
c9b6166bbb8cf8b73b42d7ecb3fa125f754a8e49e36b714718f5d14c09eff26b
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 4, 2026.

Transparency log

Release files / withoutbg-1.5.0-py3-none-any.whl

Download URL withoutbg-1.5.0-py3-none-any.whl
Size 38.1 kB
Tags Python 3
SHA-256 checksum
How to use checksums
d46d3445471d06a6df8abb6fdda42995a14f1c4cc493c69b450f95f97b898678
BLAKE2b-256 checksum
How to use checksums
84660ac8479225cd5bbe9ab7422a080ee3c2fb2237e84777c8e9276eb5ee4a58
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 4, 2026.

Transparency log

Security for withoutbg 1.5.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for withoutbg-1.5.0.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 4, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page