Self-Hosted Background Removal 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 for a drag-and-drop background removal UI. The same container also exposes the inference API under /api.

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 (headless)#

Prefer no UI? The service-* images are headless FastAPI servers: integrations, GIMP, scripts, Kubernetes, and batch jobs. Interactive OpenAPI / Swagger UI is available at http://localhost:8000/docs after the container starts.

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. No browser UI is bundled; open /docs for Swagger (see API only), or call the HTTP API directly.

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. See the screenshot under Web app.

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.

Privacy#

• No account or sign-in.
• Images are processed on the host where the container runs. The published images do not upload photos to withoutBG cloud for inference.
• No outbound network is required after the image is pulled. The model is baked in at build time.

See Open Model license for terms around the background-removal model.

Common questions#

Do my images leave my machine?

No. The Docker images process images on the host where the container runs. After you pull the image, no outbound network is required for inference. There is no withoutBG cloud upload path in these images.

Should I pull app or service?

Pull app-cpu (or app-gpu) for a drag-and-drop web UI on port 8080, with the same API under /api. Pull service-cpu (or service-gpu) for a headless FastAPI server on port 8000: integrations, GIMP, scripts, and Kubernetes.

Do I need a Hugging Face token?

Not at runtime. The ONNX model is baked into the image at build time. You only need a Hugging Face token if you build the images from source and download the model during CI or local bake.

Does it run on Apple Silicon / ARM?

Yes for CPU images: withoutbg-openweights-v3-*-cpu is published for linux/amd64 and linux/arm64. GPU images are linux/amd64 only and need an NVIDIA GPU plus the NVIDIA Container Toolkit.

Can I use it with the GIMP plugin?

Yes. Run a service-* image on port 8000, then point the GIMP 3 plugin at http://127.0.0.1:8000.

How is this different from the Pro API or the Mac app?

Docker self-hosts the open weights model on your hardware for privacy and offline/on-prem use. The Pro API is a cloud endpoint tuned for higher quality on hair, fur, and fine edges. The Mac app is a native Apple Silicon GUI with an optional Local API; use it when you want a desktop app instead of containers.

Related resources#

Docker Hub repos#

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