withoutBG Open Weights Inference (v3)

Self-host background removal. Docker images and FastAPI for the withoutBG open weights ONNX model — CPU or NVIDIA GPU.

Run a browser UI, a headless API, or both. Same open-weights quality as the Python package and Mac app, on your own server.

Docker docs → · GPU docs → · Local API docs →

See the results

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

Images

Docker Hub: withoutbg/withoutbg-openweights-v3-*

CPU images are published for linux/amd64 and linux/arm64 (Intel/AMD and Apple Silicon / ARM servers). GPU images are linux/amd64 only (NVIDIA CUDA).

App image (web UI + API) — drag-and-drop background removal in the browser, same API under /api:

Service image (API only / headless) — FastAPI with no UI. Interactive OpenAPI / Swagger at /docs:

Quick start

# Web UI + API (CPU) — open http://localhost:8080
docker run --rm -p 8080:8080 withoutbg/withoutbg-openweights-v3-app-cpu:latest

# API only (CPU) — OpenAPI at http://localhost:8000/docs
docker run --rm -p 8000:8000 withoutbg/withoutbg-openweights-v3-service-cpu:latest

GPU images require an NVIDIA GPU and the NVIDIA Container Toolkit:

docker run --rm --gpus all -p 8000:8000 withoutbg/withoutbg-openweights-v3-service-gpu:latest
docker run --rm --gpus all -p 8080:8080 withoutbg/withoutbg-openweights-v3-app-gpu:latest

After baking locally, use Compose:

docker compose up app-cpu

Build

docker buildx bake -f docker-bake.hcl

Build a single image:

docker buildx bake -f docker-bake.hcl app-cpu

Build for one platform locally (faster on Apple Silicon):

docker buildx bake -f docker-bake.hcl app-cpu --set '*.platform=linux/arm64'

CI downloads the ~1.5 GB model bundle once via huggingface_hub. Add a HF_TOKEN repository secret for reliable Hugging Face downloads from GitHub Actions.

Development

Production Docker images bake the ~1.5 GB model bundle at build time and do not hot-reload. For day-to-day work, use native dev with a one-time model download:

# 1. Download model once (~1.5 GB, cached in .cache/model/)
./scripts/dev-download-model.sh

# 2. API with hot reload (port 8000)
./scripts/dev-api.sh

# 3. UI with hot reload (port 3000, proxies /api → :8000)
cd ui && npm install && npm run dev

Edit Python under service/ or model/ and uvicorn reloads automatically. Edit React under ui/src/ and Next.js hot-reloads.

UI-only work (no real inference): NEXT_PUBLIC_USE_MOCK=true npm run dev in ui/.

Docker dev (same hot reload, cached model mount):

./scripts/dev-download-model.sh
docker compose -f docker-compose.dev.yml up --build

The first docker compose -f docker-compose.dev.yml build installs Python deps only (no model download). Rebuild only when pyproject.toml changes.

Production-like testing still uses docker buildx bake + docker compose up service-cpu.

More than Docker

This repo is the self-host path: HTTP API and browser UI on your own machine or server. Same open-weights technology powers the rest of the ecosystem:

# In-process Python (no Docker)
# https://github.com/withoutbg/withoutbg-python
uv add withoutbg

Model

The withoutBG Open Weights Model (10.8.0) is hosted at withoutbg/withoutbg-openweights-onnx. It is three ONNX graphs described by withoutbg-open-weights.onnx.json:

A trained router picks one branch per image. Fine strands, soft detail, and transparency go to the withoutBG matting branch. Hard opaque objects, flat scenes, and vehicles go to BiRefNet. Only the selected branch runs, and its alpha is upsampled to native resolution. The API reports the decision in the X-Route-Category / X-Route-Pipeline headers (routeCategory / routePipeline in JSON responses).

Builds download the bundle at a pinned Hugging Face revision (HF_REVISION in docker-bake.hcl), and every graph is SHA256-checked on load. Older single-graph bundles still load with their original behavior.

The model is licensed under the withoutBG Open Weights license. Upstream components keep their own licenses: DINOv3 (DINOv3 License), Depth Anything V2 (Apache-2.0), and BiRefNet (MIT).

License

Apache-2.0 for this repository's code. Built with DINOv3. See THIRD_PARTY_NOTICES.md for upstream model attribution.

Support

• Bugs / questions: GitHub Issues
• Docker docs: withoutbg.com/docs/open-model/docker
• Commercial: [email protected]