BackgroundRemover: removing backgrounds from images and video from the command line

What BackgroundRemover solves, and who it is aimed at

The problem is narrow and concrete: you have files on disk and you want the subject cut out without opening a photo editor for each one. BackgroundRemover is a command line tool that removes the background from images and video using AI, and the README states it was made by nadermx to power BackgroundRemoverAI.com. That origin explains the shape of the project. It is the engine behind a service, released under MIT, rather than a general-purpose editing application.

The intended user is someone who already works in a terminal. The README shows single-file image calls, folder-wide batch calls, model selection, mask-only output and background colour replacement, which is the vocabulary of a pipeline step rather than a desktop workflow. If your task is one photo and you want to click around the edges, this tool is the wrong shape for the job. If your task is two thousand product photos, or a folder of interview clips that all need the same treatment, the CLI is exactly the right shape.

The u2net models, PyTorch and the ffmpeg handoff

The mechanism is a segmentation model applied per frame. The README lists three selectable models: u2net_human_seg for humans, u2net as the general default, and u2netp as the faster, lower-accuracy option. The first run checks whether the u2net models are present locally and pulls them from the repository if they are not, so the initial invocation is slower than later ones and needs network access.

Inference runs through torch and torchvision. The README states the tool automatically detects a GPU and uses it when available, and that it falls back to CPU when no GPU is present or when a GPU error occurs. For video, ffmpeg 4.4 or newer is a hard requirement, and the README notes that video processing uses multiprocessing. That detail matters operationally: the Docker notes warn that without enough shared memory you can hit OSError: [Errno 95] Operation not supported, and the suggested fix is --shm-size=2g or higher, or --ipc=host. Nothing in the README documents how frames are buffered or how audio is carried through, so treat the video path as a black box that depends on a working ffmpeg build.

Two flags expose the segmentation internals. The -om flag writes only the binary mask instead of a composited image, which is useful if you want to do your own compositing downstream. The -bc flag takes an RGB triple such as 255,0,0 and replaces the removed area with that flat colour. The -a flag enables alpha matting, with -af, -ab, -ae and -az controlling foreground threshold, background threshold, erosion size and base size. The README's own guidance is that erosion values from 1 to 5 give sharper edges suited to cartoons and graphics, while 15 to 25 give softer edges suited to portraits. That is a real trade-off baked into one number.

Installing BackgroundRemover from PyPI, and a first image

The README's requirements are python >= 3.6, the matching python-dev package for your interpreter version, a stable torch and torchvision, and ffmpeg 4.4 or newer. The README is explicit that you must install both python and the dev package for the same version, and it gives the apt example for Debian-style systems.

sudo apt install ffmpeg python3.6-dev

Install PyTorch first, choosing the index URL that matches your hardware. The README gives the CPU-only command and separate CUDA 11.8 and 12.1 commands, and points at the PyTorch site for other CUDA versions.

pip3 install torch torchvision --index-url https://download.pytorch.org/whl/cpu

Then install the tool itself from PyPI. The README upgrades pip first.

pip install --upgrade pip
pip install backgroundremover

With that done, the first real use is a single image. The README's example writes a PNG regardless of the input format.

backgroundremover -i "/path/to/image.jpeg" -o "output.png"

On this first run the tool checks for the u2net models and downloads them if they are missing, so expect a pause and some network traffic. The output is a PNG with the background removed. Supported image inputs are .jpg, .jpeg, .png, .heic and .heif, with HEIC and HEIF requiring pillow-heif, which is listed in requirements.txt. To check whether the GPU path is actually active, the README supplies this one-liner.

python3 -c "import torch; print('GPU available:', torch.cuda.is_available()); print('GPU name:', torch.cuda.get_device_name(0) if torch.cuda.is_available() else 'N/A')"

If that prints False, you installed a CPU build and the README's GPU section is the place to look next. For batch work, -if and -of take input and output folders; if you omit -of, outputs land in the input folder prefixed with output_, which is convenient and also a good way to accidentally overwrite your working directory's naming scheme.

Running it in Docker, and the shared memory trap

The repository ships a Dockerfile that builds on continuumio/miniconda3:23.5.2-0, installs ffmpeg from conda-forge, installs the package with pip, then copies the conda tree into a debian:bullseye-slim runtime image. It declares /root/.u2net as a volume and sets the entrypoint to python -m backgroundremover.cmd.cli, so the container behaves like the CLI.

The README's alias-based approach is the practical part. The basic alias downloads models on every run; the second alias mounts ~/.u2net so they persist; the third adds --shm-size=2g for video.

git clone https://github.com/nadermx/backgroundremover.git
cd backgroundremover
docker build -t bgremover .
alias backgroundremover='docker run -it --rm --shm-size=2g -v "$(pwd):/tmp" -v "$HOME/.u2net:/root/.u2net" bgremover:latest'

The mount of the current directory to /tmp is what makes input and output paths resolve, so paths you pass to -i and -o are container paths. The README also documents running without pip at all, by cloning the repository, creating a virtual environment, installing requirements and invoking the module directly with python -m backgroundremover.cmd.cli. That route exists for people who want to modify the code, and it is the only documented path for doing so.

Where BackgroundRemover is the wrong tool

The clearest limitation is edge quality on hard subjects. The default output is described in the README as soft, natural edges, and the alpha matting controls exist precisely because that default is not always what you want. Tuning -ae by hand per image is not a batch-friendly operation, and the README gives ranges rather than a rule for picking a value. If your subject is hair against a busy background, or a translucent object, expect to spend time on parameters.

The second limitation is the video path's fragility. It depends on ffmpeg 4.4 or newer, on multiprocessing, and on adequate shared memory in containerised runs. The README documents the OSError: [Errno 95] symptom and two workarounds, but it does not document memory requirements per resolution or per clip length, so you cannot size a machine from the documentation alone. You have to measure.

The third is that this is a segmentation model, not an editor. There is no documented interactive refinement, no undo, no layer model. The -om flag gives you a mask to composite elsewhere, which is the honest answer for anyone who needs control: use BackgroundRemover to produce the matte, then do the rest in a tool built for it. Finally, the README does not document rollback or version pinning behaviour for the downloaded models, so if a model download changes, the documentation is silent on how to return to a previous state.

BackgroundRemover against rembg and hosted background removers

The obvious open source alternative is rembg, which is also a Python segmentation tool built around u2net-family models. The difference in approach is scope. rembg is primarily an image library and CLI; BackgroundRemover's distinguishing feature is that video is a first-class input, with ffmpeg and multiprocessing wired in, plus a documented Docker image and a server entry point (backgroundremover-server, declared in setup.py's console_scripts alongside backgroundremover). If your workload is images only, the video machinery is weight you are carrying for nothing, and a lighter image-focused tool is the better fit.

Against hosted services such as the ones behind the search terms people use for this project, the trade is control versus convenience. A hosted remover needs no Python, no PyTorch build and no ffmpeg, and it usually handles the hard edges for you. BackgroundRemover runs locally, which means your files never leave the machine, and it costs nothing beyond compute. It also means you own the failure modes: CUDA mismatches, shared memory limits, ffmpeg versions. The README's troubleshooting section is essentially a list of those failure modes, which tells you where users actually get stuck.

Licence, maintenance and what upgrading costs

The project is MIT licensed, and setup.py declares license="MIT". MIT is permissive: you can use it commercially, modify it and redistribute it, provided the copyright notice and licence text are retained. The repository carries LICENSE.txt at the top level. That is a summary of the licence terms, not legal advice; if you are embedding this in a product, read LICENSE.txt and the licences of the dependencies, particularly torch and torchvision, whose terms are separate from this project's.

The repository is not archived, and the last push was on 2026-07-10, which coincides with the v0.4.5 release on the same date. The release history shows v0.4.4 on 2026-06-09 and v0.4.1 on 2026-02-17, so the cadence across 2026 has been roughly every one to four months. Version 0.4.5 is the version declared in setup.py, so the published package and the repository are in step.

Upgrade cost is dominated by the PyTorch dependency rather than by BackgroundRemover itself. requirements.txt pins torch>=1.13.0 and torchvision>=0.14.0 with lower bounds only, so a fresh install can pull a much newer torch than you tested with. If you need reproducibility, pin torch and torchvision yourself in your own environment rather than relying on the requirements file. The models are a second moving part: they are fetched at runtime from the repository, and the README does not document how to pin or vendor a specific model revision.

Editorial conclusion

Adopt BackgroundRemover if you need a scriptable, local pipeline for images or short video and you are comfortable with Python, PyTorch and ffmpeg. Do not adopt it if you want a hosted editor, a Photoshop-style selection workflow, or if you cannot install a CUDA build of PyTorch for large video jobs. Before committing, run one image through the pip install and confirm the u2net models download, then run the same image with -a and -m u2net_human_seg to see whether alpha matting and the human segmentation model actually beat the default on your material.

Frequently asked questions

Official sources

1. License: MIT
2. nadermx/backgroundremover on GitHub
3. Project website
4. README
5. Releases