A fast, private background-removal tool that runs entirely on your own machine.

Unofficial open-source project. Not affiliated with remove.bg or Canva Austria GmbH.

An offline alternative for people who want a workflow similar to cloud background-removal services such as remove.bg, without uploading images or paying API costs. Everything runs locally — no limits, no account, no API.

It ships with ISNet as the default (fast and high quality) and also includes BiRefNet (2024) — one of the best open-source models for background segmentation — for when you want maximum quality.

Features

• Web UI with drag & drop (paste from clipboard works too)
• Processing queue — drop several images at once and they are processed one by one; each result is kept in its own card, nothing gets overwritten
• Persistent sessions — results are saved locally (in the browser) and grouped into sessions in the sidebar; they survive reloads until you delete them. "New session" starts a fresh batch without losing the old ones
• Download as PNG, WEBP or JPG, with the background you choose (transparent or a solid color) — per image or all at once
• Per-result background to check contrast, independent of the global default
• First-run setup screen with a real download progress bar
• Models page in the top menu: what each model is best for, which ones are downloaded, plus buttons to download or delete each one (with progress)
• Desktop app — run it in a native window with rm-bg desktop (Electron)
• rm-bg command line — start/stop, manage models and update from the terminal
• Switch between 6 models depending on the case (general, portrait, lite, etc.)
• Alpha matting mode for fine edges (hair, plants)
• 100% local processing — your images never leave your machine
• No limits on count or resolution (beyond the file-size cap)

Requirements

• Mac with Apple Silicon (also works on Intel and other systems, just slower)
• Python 3.9 or newer
• ~2 GB of free disk space (models + dependencies)

Check that you have Python:

python3 --version

If you don't, install it from python.org or with Homebrew: brew install python

Install and run

Needs Node.js and Python 3.9+ already installed (Node can't install Python for you).

Option A — just try it (npx, temporary)

npx -y remove-background-local        # runs the web app right now

npx downloads the package temporarily, runs it, and opens http://127.0.0.1:7860. It does not leave a command installed — good for a quick try. (For the desktop window: npx -y remove-background-local desktop.)

Option B — install it (npm, permanent + the rm-bg command)

npm install -g remove-background-local   # installs the `rm-bg` command everywhere
rm-bg web                                # then run it whenever you want
rm-bg desktop                            # ...or as a native window

This is the recommended way for regular use and the desktop app. Update later with rm-bg update. (npm install -g only installs — it doesn't start anything; you run rm-bg ... afterwards.)

Option C — from source

git clone https://github.com/tecnomanu/remove-background-local
cd remove-background-local
./run.sh

The first run will:

1. Create a .venv virtual environment
2. Install the Python dependencies (can take 2–5 minutes)
3. Start the server

After that, every ./run.sh starts in a few seconds.

Open in your browser: http://127.0.0.1:7860

The first time you use a model it is downloaded automatically (between 100 and 400 MB depending on the model). After that it stays cached in ~/.u2net/.

Moved the folder? A Python virtualenv stores absolute paths, so a copied/moved .venv is broken. run.sh detects this automatically and rebuilds the environment — you don't have to do anything.

Commands (rm-bg)

When installed via npm (globally or with npx), you get the rm-bg command:

rm-bg web                     # start the web server (foreground)
rm-bg start                   # start it in the background
rm-bg stop                    # stop the background server
rm-bg init                    # set up and download the default model
rm-bg desktop                 # open as a desktop app (Electron)
rm-bg models ls               # list models and which are downloaded
rm-bg models pull --model birefnet-general   # download a model
rm-bg models rm   --model birefnet-general   # delete a downloaded model
rm-bg update                  # update to the latest version
rm-bg help                    # show all commands

Background server state (the pidfile and logs) lives in ~/.remove-background-local/.

Desktop app

rm-bg desktop

This opens the same UI in a native window (built with Electron): it starts the local server behind the scenes and shows it as a regular app, no browser tab needed. The first run downloads the Electron runtime once into ~/.remove-background-local/ (it is not bundled, to keep the base install small). Everything else — models, sessions, privacy — works exactly like the web version.

Install it as an app:

rm-bg desktop install      # add it to your system as an app
rm-bg desktop uninstall    # remove it

What this does per platform:

• macOS — builds a real Remove Background Local.app into /Applications (its own name, icon and bundle id). Open it from Launchpad/Applications. Built locally, so there is no Gatekeeper warning.
• Linux — adds a .desktop launcher to ~/.local/share/applications, so "Remove Background Local" shows up in your application menu.
• Windows — creates a Start Menu shortcut (with the app icon).

All of them launch the same desktop window and use the Python environment under ~/.remove-background-local/ (run rm-bg init to recreate it if needed). A signed/notarized installer for distributing to other people would need a platform developer account — out of scope for now.

Updating the installed app: rm-bg update updates the npm package and then refreshes the installed desktop app automatically. On Linux/Windows the launcher points at the npm package, so it is current after any npm install -g remove-background-local@latest; on macOS the .app bundles a copy of the code, so it is rebuilt (run rm-bg desktop install if you updated npm by hand).

Usage

1. Drag one or more images onto the box (or click to choose, or paste with Cmd+V)
2. They are added to the queue and processed one by one
3. Download each result, or use Download all

Which model to choose

Times below are rough per-image figures on Apple Silicon (CPU execution).

| Model | When to use it | Speed | |---|---|---| | isnet-general-use | Default. Fast and very good quality for any image. | ~1s | | u2net | The classic — good for simple products. | ~0.5s | | u2net_human_seg | People only. | ~0.5s | | birefnet-general-lite | Higher quality, still reasonable. | ~9s | | birefnet-general | Best quality for any image. | ~20s | | birefnet-portrait | People, best quality (difficult hair). | ~20s |

Why ISNet by default and not BiRefNet? BiRefNet is the highest-quality model, but it is large (~930 MB) and slow on CPU. ISNet is the better default for a tool that should "just work" — fast, reliable, and still excellent quality. Switch to a BiRefNet model from the selector whenever you want maximum quality and don't mind the wait.

Alpha matting (optional)

In the "Advanced options" section you can enable alpha matting. It's slower but gives better edges in difficult cases (loose hair, transparency, mesh).

• FG threshold: pixels clearly belonging to the object (default 240, raise it if it eats parts of the object)
• BG threshold: pixels clearly belonging to the background (default 10, lower it if it leaves background leftovers)
• Erode: fine edge adjustment

Advanced configuration

Environment variables before running ./run.sh:

HOST=0.0.0.0 PORT=8000 ./run.sh         # Change port / expose to the local network
REMBG_MODEL=birefnet-general ./run.sh   # Change the default model
MAX_UPLOAD_MB=100 ./run.sh              # Raise the size limit

# Execution provider (advanced). CPU is the default because the onnxruntime
# CoreML provider hangs on some models on Apple Silicon. CPU is fast enough for
# the lighter models. Only change this if you know what you are doing:
REMBG_PROVIDERS=CoreMLExecutionProvider,CPUExecutionProvider ./run.sh

Programmatic use (no UI)

The POST /remove endpoint accepts multipart/form-data:

curl -X POST http://127.0.0.1:7860/remove \
  -F "[email protected]" \
  -F "model=birefnet-general" \
  -o photo_nobg.png

Process a whole folder in batch:

for f in *.jpg; do
  curl -s -X POST http://127.0.0.1:7860/remove \
    -F "image=@$f" \
    -F "model=birefnet-general" \
    -o "${f%.*}_nobg.png"
  echo "ok: $f"
done

Endpoints

| Method | Path | Description | |---|---|---| | GET | / | Web UI | | POST | /remove | Remove background, returns a transparent PNG | | GET | /models | List of available models (with approx sizes) | | GET | /model_status | Load state of a model (idle / loading / ready / error) | | POST | /warmup | Start loading a model in the background (non-blocking) | | GET | /health | Server status |

Expected performance on Mac Apple Silicon (CPU)

With the default ISNet model: roughly ~1 second per image. U2Net is even faster (~0.5s). The BiRefNet models are slower (~9–20s) but give the highest quality.

The first request to a given model is slower because it downloads (one time) and loads the model into memory. The first-run setup screen shows this is happening.

Troubleshooting

onnxruntime install error: on some older Macs it can fail. Try:

.venv/bin/pip install onnxruntime --upgrade

The model won't download: check your internet connection — the first time it needs to fetch the model from Hugging Face / GitHub. After that it works 100% offline.

Bad quality on some image: try another model from the selector. For maximum quality, use a BiRefNet model; for people with difficult hair, BiRefNet portrait + alpha matting is usually best.

Port 7860 in use: change it with PORT=8000 ./run.sh

I moved the project folder and it stopped working: a Python virtualenv stores absolute paths, so a copied/moved .venv is broken. run.sh detects this and rebuilds the environment automatically — just run ./run.sh again.

Development

Run the test suite (fast, no network needed — model loading is mocked):

./run_tests.sh

Contributing or using an AI agent on this repo? Read AGENTS.md — it covers the architecture, conventions (English, no emojis, CPU default), and the rule that every commit must keep the tests green. CI runs the tests on every push.

Project structure

remove-background-local/
├── server.py            # FastAPI backend (+ `models` CLI)
├── static/
│   └── index.html       # Frontend (single file)
├── bin/
│   └── cli.js           # `rm-bg` launcher / subcommands
├── electron/
│   └── main.js          # Desktop app (Electron) main process
├── package.json         # npm package (bin: rm-bg)
├── requirements.txt     # Python dependencies
├── requirements-dev.txt # Test dependencies
├── run.sh               # Startup script (from source)
├── run_tests.sh         # Test runner
├── tests/               # pytest suite
├── CHANGELOG.md         # Version history
├── AGENTS.md            # Guide for contributors / AI agents
└── README.md            # This file

Model licenses

• BiRefNet: MIT (commercial use OK)
• ISNet: Apache 2.0 (commercial use OK)
• U2Net: Apache 2.0 (commercial use OK)

All open source and usable commercially at no cost.

License

MIT