Self-host with Docker#

Pick the right image#

Start here if you are not sure which one to pull.

Default recommendation: pull withoutbg/withoutbg-openweights-v3-app-cpu:latest if you want to see it working in under a minute. Switch to service-* when you are integrating programmatically and do not need the UI.

When Docker is not the best fit:

• Python library — pip install withoutbg if you want to embed inference in an existing Python process without container overhead.
• Mac app — native macOS app for a desktop GUI with no terminal.
• GIMP plugin — GIMP 3 plugin (source on GitHub) talks to a local API on port 8000 (Docker service-* or Mac server app). Install the plugin, start a backend, then use Tools ▸ WithoutBG ▸ Remove Background….
• No install — Hugging Face Space or the hosted demo at withoutbg.com.

Quick start#

Web app (most people start here)#

Open http://localhost:8080.

First startup loads and warms the model (usually 10–30 seconds on CPU). Wait until /ready returns {"status":"ready"} before uploading large batches.

API only#

On app images, prefix paths with /api (e.g. /api/v1/remove-background on port 8080).

# Liveness (also used by the GIMP plugin to show server status)
curl http://localhost:8000/health

# Readiness (503 until model is warmed up)
curl http://localhost:8000/ready

/health response:

{
  "status": "ok",
  "model": "withoutbg-openweights-oss",
  "version": "4.1.0"
}

JSON API (web UI, scripts)#

Send a base64-encoded image; get data URLs back.

# Works on macOS and Linux
IMAGE_B64=$(base64 < photo.jpg | tr -d '\n')
curl -X POST http://localhost:8000/v1/remove-background \
  -H "Content-Type: application/json" \
  -d "{\"image\":\"${IMAGE_B64}\"}"

Request body:

{
  "image": "<raw base64 string, or data:image/jpeg;base64,...>"
}

Response fields:

Example response:

{
  "processed": "data:image/png;base64,...",
  "alphaMatte": "data:image/png;base64,...",
  "latencyMs": 842
}

JSON error responses use {"detail": "..."}.

Raw image API (GIMP plugin and local clients)#

POST the image bytes directly, with no base64 wrapping. The server detects the request format from Content-Type.

# Transparent cutout (default)
curl -X POST http://localhost:8000/v1/remove-background \
  -H "Content-Type: image/png" \
  --data-binary @photo.png \
  -o cutout.png \
  -D -

# Alpha matte (what the GIMP plugin requests)
curl -X POST "http://localhost:8000/v1/remove-background?output=matte" \
  -H "Content-Type: image/png" \
  --data-binary @photo.png \
  -o matte.png \
  -D -

Accepted input: raw body with Content-Type: image/* (JPEG, PNG, WebP, etc.), or multipart/form-data with a field named image.

Response: 200 with Content-Type: image/png, body is the PNG bytes, and header X-Latency-Ms: <milliseconds>.

Raw-image error responses use {"error": "..."}.

Full schema and try-it-out UI: http://localhost:8000/docs

GIMP plugin#

The withoutBG GIMP 3 plugin removes backgrounds inside GIMP by calling a local API on port 8000 (Docker service-* or Mac server). All processing stays on your machine.

1. Start a local API on port 8000 (Docker service-* or Mac server app; see API only above).
2. Install the plugin from github.com/withoutbg/withoutbg-gimp (./install.sh, then restart GIMP).
3. In GIMP: Tools ▸ WithoutBG ▸ Remove Background…
4. Confirm the dialog shows the server as ready at http://127.0.0.1:8000 (override the URL in the dialog if you mapped a different host port).

The plugin POSTs a PNG to /v1/remove-background?output=matte, upscales the returned alpha matte to your layer size, and attaches it as an unapplied layer mask.

GPU images#

Requires an NVIDIA GPU and the NVIDIA Container Toolkit.

# API
docker run --rm --gpus all -p 8000:8000 \
  withoutbg/withoutbg-openweights-v3-service-gpu:latest

# Web app
docker run --rm --gpus all -p 8080:8080 \
  withoutbg/withoutbg-openweights-v3-app-gpu:latest

If the container starts but inference is slow, check logs for the active ONNX Runtime provider. GPU images require CUDAExecutionProvider; they will fail fast at startup if CUDA is unavailable.

The four images#

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

Service images (API only)#

Headless FastAPI server. Use these for backends, batch jobs, microservices, and production deployments.

Endpoints (direct on port 8000):

App images (web UI + API)#

Same inference service, plus a static Next.js UI served by nginx. The API is proxied under /api.

What you get on port 8080:

• / — drag-and-drop background removal UI
• /api/v1/remove-background — same API as the service image
• /health — proxied liveness check

At a glance#

Service vs app#

CPU vs GPU#

Docker Compose#

For local or server deployment with published images:

services:
  app:
    image: withoutbg/withoutbg-openweights-v3-app-cpu:latest
    ports:
      - "8080:8080"
    restart: unless-stopped

  # Uncomment for API-only deployment:
  # api:
  #   image: withoutbg/withoutbg-openweights-v3-service-cpu:latest
  #   ports:
  #     - "8000:8000"
  #   restart: unless-stopped

  # GPU variant (requires nvidia-container-toolkit):
  # api-gpu:
  #   image: withoutbg/withoutbg-openweights-v3-service-gpu:latest
  #   ports:
  #     - "8000:8000"
  #   deploy:
  #     resources:
  #       reservations:
  #         devices:
  #           - driver: nvidia
  #             count: all
  #             capabilities: [gpu]

Save as compose.yaml, then:

docker compose up -d

The source repository also ships a docker-compose.yml wired to locally built image names. Use that when developing from source with docker buildx bake.

Image tags#

For reproducible deployments, prefer a sha-* or semver tag over latest.

System requirements#

Rough guidance. Actual latency depends on image size and hardware.

CPU images#

• RAM: 4 GB minimum, 8 GB recommended (model + ONNX Runtime + FastAPI)
• Disk: ~2 GB pulled image size
• CPU: Any x86_64 or arm64 host that runs Docker; inference is slower on low-core machines
• GPU: Not required

Expect roughly 2–15 seconds per image on a modern laptop CPU for a typical photo.

GPU images#

• GPU: NVIDIA GPU with CUDA support (CUDA 12.x runtime in image)
• Driver: Recent NVIDIA driver compatible with CUDA 12.4
• RAM: 8 GB system RAM recommended
• Disk: ~5–8 GB pulled image size (CUDA base layer)

GPU images are significantly faster for repeated inference but have a larger footprint and require NVIDIA Container Toolkit on the host.

Production notes#

Health checks#

• Use /health for liveness (is the process running?).
• Use /ready for readiness (is the model loaded?). Returns 503 until warmup completes. Important for Kubernetes readinessProbe so traffic is not routed to a cold container.

Kubernetes probes (service image on port 8000):

readinessProbe:
  httpGet:
    path: /ready
    port: 8000
  initialDelaySeconds: 5
  periodSeconds: 5
livenessProbe:
  httpGet:
    path: /health
    port: 8000
  periodSeconds: 10

Scaling#

• Each container runs a single uvicorn worker with one loaded model session. Scale horizontally by running multiple containers behind a load balancer rather than increasing --workers.
• Inference is serialized per container (thread lock on the model). For high throughput, run several replicas.

Security#

• Images run as non-root user withoutbg (uid 1000).
• No outbound network is required after the image is built. The model is baked in at build time.
• Put a reverse proxy (nginx, Caddy, Traefik) in front for TLS termination if exposed beyond localhost.

Request limits#

• App images accept uploads up to 50 MB via nginx (client_max_body_size).
• Input images are letterboxed to 1024×1024 for inference; output is returned at the original resolution.

Troubleshooting#

Build from source#

To build locally instead of pulling from Docker Hub:

git clone https://github.com/withoutbg/withoutbg-inference.git
cd withoutbg-inference
docker buildx bake -f docker-bake.hcl          # all four images
docker buildx bake -f docker-bake.hcl app-cpu  # single target
docker compose up app-cpu                       # run locally built image

CI publishes to Docker Hub on every push to main and on v3.* release tags.

Related resources#

Docker Hub repos#

• service-cpu
• service-gpu
• app-cpu
• app-gpu