GIMP 3 Plugin for Background Removal

Requirements#

Start a local API#

The plugin talks to a withoutBG HTTP API on 127.0.0.1. Pick one backend:

Docker service (port 8000)#

Cross-platform. Uses the open weights v3 ONNX model from withoutbg-inference.

Full Docker docs: /docs/open-model/docker

Mac app Local API (port 8000)#

macOS only. withoutBG for Mac is one app: a desktop batch UI plus an optional Local API in the menu bar. Use the Local API when you want GIMP (or scripts) to call withoutBG on your machine. On Apple Silicon, inference uses Core ML.

1. Install withoutBG for Mac (download from GitHub Releases).
2. Start the Local API from the empty-state Start Local API button, or from the menu bar icon. Default URL: http://127.0.0.1:8000
3. Confirm the menu bar shows Local API Running before using the plugin.

Docker service-* and the Mac app Local API both use port 8000 by default, so the plugin works with either backend without changing settings. Run one backend at a time on that port.

The plugin dialog accepts any server URL if you change the port. More detail: /mac · Local API docs.

Verify the API#

curl http://127.0.0.1:8000/health

Expected response:

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

Wait until /ready returns {"status":"ready"} on first startup (model warmup).

Install the plugin#

Or clone and run locally:

git clone https://github.com/withoutbg/withoutbg-gimp.git
cd withoutbg-gimp
./install.sh

Restart GIMP. The plugin appears under:

Tools ▸ WithoutBG ▸ Remove Background…

Manual install paths#

Layout after install:

plug-ins/withoutbg/withoutbg.py

Usage#

1. Open an image in GIMP and select the layer to process.
2. Go to Tools ▸ WithoutBG ▸ Remove Background…
3. Check the dialog. It shows server status (model name and version from /health).
4. Confirm Server URL is http://127.0.0.1:8000 (default for both Docker and the Mac app Local API).
5. Click Remove Background.

The plugin:

1. Exports the active layer as PNG (longest side capped at 1024 px before upload).
2. POSTs to /v1/remove-background?output=matte with Content-Type: image/png.
3. Upscales the returned matte to full layer resolution.
4. Adds it as an unapplied layer mask on the active layer.

To commit the mask: Layer ▸ Mask ▸ Apply Layer Mask.

Server URL#

Default in the plugin: http://127.0.0.1:8000 (same for Docker service-* and the Mac app Local API).

You can override the URL per session in the plugin dialog; GIMP remembers the last value.

To change the baked-in default, edit SERVER_URL at the top of withoutbg/withoutbg.py.

API the plugin uses#

Both backends expose the same endpoints:

The plugin reads the X-Latency-Ms response header but does not display it.

Troubleshooting#

Uninstall#

rm -rf ~/Library/Application\ Support/GIMP/3.0/plug-ins/withoutbg   # macOS
rm -rf ~/.config/GIMP/3.0/plug-ins/withoutbg                        # Linux

Restart GIMP.

Common questions#

Does the GIMP plugin upload my images to the cloud?

No. The plugin only talks to a withoutBG HTTP API on 127.0.0.1 (Docker service or Mac app Local API). Processing stays on your machine.

Does it work with GIMP 2.x?

No. The plugin requires GIMP 3.0. GIMP 2.x is not supported.

Do I need Docker, or can I use the Mac app?

Either works. Run the Docker withoutbg service on port 8000, or start the Local API from withoutBG for Mac. Default Server URL is http://127.0.0.1:8000 for both.

What does the plugin add to my layer?

An unapplied layer mask built from the grayscale alpha matte. To commit the cutout, use Layer ▸ Mask ▸ Apply Layer Mask in GIMP.

Is Windows supported?

The plugin itself targets GIMP 3 on macOS and Linux. On Windows, use the Docker service as the local API backend with GIMP 3 if you run GIMP there.

Why does the layer mask look soft at the edges?

The active layer is capped at 1024 px on the longest side before inference, then the matte is upscaled. Soft edges at the mask boundary are expected; paint on the mask to refine.

Related#