withoutbg Python Library

The withoutBG Open Weights Model ONNX graph embeds DINOv3-derived weights and components. Users redistributing these weights must comply with the withoutBG Open Model License, which combines:

• Apache 2.0 for withoutBG-authored portions.
• Meta DINOv3 License for DINOv3 portions.

When distributing the Open Weights Model or derivatives containing DINOv3 Materials, you must:

1. Include a copy of the Meta DINOv3 License (LICENSE-DINOv3).
2. Prominently display "Built with DINOv3" in related product documentation, app About screens, or model cards.
3. Comply with Meta's trade-control and prohibited-use restrictions.

Model version 10.0.0 introduces a fixed I/O canvas size of 448×448 (previously 1024 input / 768 output).

Integration Note: If your implementation relies on hard-coded 1024/768 letterbox sizes, you must update your logic to read the canvas_size and shapes directly from the sidecar metadata file (withoutbg-open-weights.onnx.json). If the sidecar is absent, the package defaults to 448.

All remove_background methods return a PIL Image in RGBA mode.

• PNG/WebP: Preserves transparency.
• JPEG: Transparency is dropped silently (the background will be filled, typically with black or white depending on implementation, but the alpha channel is lost).

Use WithoutBG.open_weights() to run the model locally on your machine. This mode is free, private, and works offline. On the first run, it will download approximately 455 MB of weights from Hugging Face.

Note: Keep the model object alive if processing multiple images to avoid reloading weights repeatedly.

from withoutbg import WithoutBG

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

Install the withoutbg package using uv:

uv add withoutbg

If you distribute the withoutBG software or the Open Weights Model, you must satisfy the following attribution and licensing requirements:

1. Include a copy of the Apache License 2.0 (LICENSE file).
2. Include the THIRD_PARTY_LICENSES.md file.
3. Include a copy of the Meta DINOv3 License (LICENSE-DINOv3) if distributing model weights or derivatives that embed DINOv3 Materials.
4. Include the NOTICE file.
5. Retain all original copyright notices.
6. Include attribution to withoutbg.com in any public usage.
7. Display "Built with DINOv3" when distributing the Open Weights Model (as required by the Meta DINOv3 License).

Use WithoutBG.api() to access the Cloud API, which provides higher quality results (especially for hair and fur) without requiring local GPU/CPU resources. You must provide an api_key or set the WITHOUTBG_API_KEY environment variable.

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")

The Python SDK (pip install withoutbg) has moved from a sub-package in the withoutbg/withoutbg monorepo to its own standalone repository.

• To use the Python package: Instead of cloning the monorepo, use pip install withoutbg or clone this repository directly.
• To use the self-hosted Docker application: The web UI, Docker, and FastAPI components previously located in apps/web/ have moved to the withoutbg-inference repository.

The model architecture has changed from a multi-file setup (depth, ISNet, matting, refiner) to a single unified ONNX graph.

• Environment Variable: Use WITHOUTBG_MODEL_PATH to point to the unified .onnx file.
• Deprecated Variables: The following variables are no longer used: WITHOUTBG_DEPTH_MODEL_PATH, WITHOUTBG_ISNET_MODEL_PATH, WITHOUTBG_MATTING_MODEL_PATH, and WITHOUTBG_REFINER_MODEL_PATH.
• Metadata: A sidecar metadata file named withoutbg-open-weights.onnx.json must be located in the same directory as the .onnx file.

The WithoutBG class provides two distinct ways to perform background removal via factory methods:

1. Local Open Weights Model (WithoutBG.open_weights()): Runs ONNX-based models locally on your machine. It is ideal for privacy or offline use. The model is downloaded from Hugging Face on the first use if a model_path is not provided.
2. Cloud API (WithoutBG.api()): Uses the withoutbg.com cloud service for high-quality background removal. This is ideal for high-performance needs without local compute requirements. It requires an API key.

Both methods return an object that implements the same remove_background and remove_background_batch interface.

from withoutbg import WithoutBG

# For local execution
model = WithoutBG.open_weights()

# For cloud execution
model = WithoutBG.api(api_key="your_api_key")

Use the following environment variables to configure the library:

| Variable | Description | |---|---|---| | WITHOUTBG_API_KEY | API key for Cloud mode (alternative to api_key= argument) | | WITHOUTBG_MODEL_PATH | Path to a local .onnx file (skips Hugging Face download). Note: Keep the sidecar metadata file withoutbg-open-weights.onnx.json next to the ONNX file. |