# BackgroundRemover: CLI tool to remove image and video backgrounds with U2Net AI

> A command-line tool that uses deep learning (U2Net models) to detect and remove backgrounds from images and videos. Works on CPU or GPU, supports multiple image formats and video codecs, and can replace backgrounds with custom colors or images.

**nadermx/backgroundremover** — Background Remover lets you Remove Background from images and video using AI with a simple command line interface that is free and open source.

- Repository: https://github.com/nadermx/backgroundremover
- Website: https://backgroundremoverai.com
- Stars: 8,082 · Forks: 649
- Language: Python
- License: MIT
- Published: 2026-09-16 · Updated: 2026-09-16 · Language: en
- Canonical page: https://hysenlabs.com/projects/nadermx-backgroundremover

## BackgroundRemover uses U2Net to separate foreground from background

BackgroundRemover is a command-line tool that reads images and videos, applies a deep learning model to detect the foreground, and outputs a version with the background removed. The tool uses the U2Net architecture, which is a trained neural network specifically designed for semantic segmentation. The tool downloads the model on first run if it is not already cached.

BackgroundRemover supports multiple models: u2net for general objects, u2net_human_seg for human subjects, and u2netp for faster processing with lower accuracy. Different models are optimized for different subjects. Selecting the right model affects both the accuracy and speed of background removal.

## Installing BackgroundRemover with dependencies

BackgroundRemover requires several components: Python 3.6 or later, the matching python-dev package for your Python version, PyTorch and torchvision, and ffmpeg 4.4 or newer. Plan ahead: PyTorch is a large download, and GPU versions are especially large. Ensure you have enough disk space before installation.

Install the package itself from PyPI:

```bash
pip install --upgrade pip
pip install backgroundremover
```

For PyTorch, visit pytorch.org for CPU or GPU installation instructions. For CPU-only use (no GPU acceleration):

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

For GPU support with CUDA 11.8:

```bash
pip3 install torch torchvision --index-url https://download.pytorch.org/whl/cu118
```

For CUDA 12.1:

```bash
pip3 install torch torchvision --index-url https://download.pytorch.org/whl/cu121
```

Install ffmpeg and python-dev on Linux:

```bash
sudo apt install ffmpeg python3.6-dev
```

The first time you run the program, it will download the U2Net models if they are not cached locally. Models are cached in `~/.u2net` by default, so subsequent runs do not re-download.

## Removing backgrounds from single images and folders

To remove the background from a single image:

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

Supported image formats are .jpg, .jpeg, .png, .heic and .heif (HEIC/HEIF support requires the pillow-heif package installed). BackgroundRemover converts transparent backgrounds to PNG by default, allowing downstream tools to place foreground on any background.

To process all images in a folder:

```bash
backgroundremover -if "/path/to/image-folder" -of "/path/to/output-folder"
```

If no output folder is specified, results are saved in the input folder with an `output_` prefix. The tool processes all supported image and video files in the folder automatically, making batch processing simple. For fine-grained control over edge quality, enable alpha matting:

```bash
backgroundremover -i "/path/to/image.jpeg" -a -ae 5 -o "output.png"
```

The `-a` flag enables alpha matting for refined edges. The `-ae` flag sets erosion size (1-25); smaller values (1-5) produce sharper edges for cartoons and graphics, while larger values (15-25) produce softer, more natural edges for portraits and photographs. Additional parameters for fine control include `-af` for foreground threshold (default 240) and `-ab` for background threshold (default 10), allowing you to adjust sensitivity to subtle background gradations and challenging lighting conditions. The `-az` parameter controls base size (default 1000), affecting the resolution at which the model processes the image and trades off memory usage against detail preservation.

## Processing videos and using GPU acceleration

BackgroundRemover can remove backgrounds from videos using the same syntax as images. Process video files by pointing the `-i` flag at a video file and `-o` at the output video file. Video output formats depend on your ffmpeg installation and the codec flags used. Processing videos requires more computation than images because each frame must be processed sequentially, making GPU acceleration especially important for video workflows.

GPU acceleration is automatic and recommended. BackgroundRemover detects GPU availability and uses CUDA if available, providing 5-10x speed improvements over CPU for both images and videos. To verify GPU is being used and detect your GPU device:

```bash
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 GPU is not detected, ensure you installed the CUDA-compatible version of PyTorch matching your system's CUDA version (11.8 or 12.1). If you get out-of-memory errors during video processing, reduce the GPU batch size with `-gb 1`. The tool automatically falls back to CPU if GPU is unavailable, encounters errors, or is explicitly disabled, though CPU processing is significantly slower for video.

## Replacing backgrounds with colors or custom images

Rather than removing the background entirely, you can replace it with a solid color by specifying RGB values:

```bash
backgroundremover -i "/path/to/image.jpeg" -bc "255,0,0" -o "output.png"
```

This replaces the background with red. Similarly, `0,255,0` is green and `0,0,255` is blue. Any RGB triplet can be used, giving you full color control over the replacement background.

Alternatively, replace the background with another image:

```bash
backgroundremover -i "/path/to/image.jpeg" -bi "/path/to/background.jpg" -o "output.png"
```

This composites the foreground onto a custom background image, useful for creating product photos against specific backgrounds or virtual backgrounds for video conferencing.

You can also output only the mask (the binary segmentation map) rather than the final composite:

```bash
backgroundremover -i "/path/to/image.jpeg" -om -o "mask.png"
```

This is useful if you want to use the segmentation mask in a downstream tool, apply custom blending, or integrate the mask with other image processing workflows. The mask is a binary image where white pixels indicate foreground and black pixels indicate background.

## Running in Docker and supporting shell pipelines

A Dockerfile is included that uses Miniconda and Debian for a lightweight multi-stage build. Build and run it:

```bash
git clone https://github.com/nadermx/backgroundremover.git
cd backgroundremover
docker build -t bgremover .
alias backgroundremover='docker run -it --rm -v "$(pwd):/tmp" bgremover:latest'
```

For persistent model caching across runs (avoiding re-downloads), persist the `~/.u2net` directory:

```bash
mkdir -p ~/.u2net
alias backgroundremover='docker run -it --rm -v "$(pwd):/tmp" -v "$HOME/.u2net:/root/.u2net" bgremover:latest'
```

For video processing in Docker, adequate shared memory is required. Use the `--shm-size=2g` flag or `--ipc=host` to avoid multiprocessing errors like `OSError: [Errno 95] Operation not supported`:

```bash
docker run -it --rm --shm-size=2g -v "$(pwd):/tmp" bgremover:latest
```

BackgroundRemover also supports Unix pipelines, allowing you to read from stdin and write to stdout. This enables integration into shell scripts without intermediate files. For users who prefer graphical interfaces, the repository includes a GUI implementation accessible via `background_remover_gui.py`, providing the same background removal functionality in a visual environment. Additionally, BackgroundRemover supports HTTP server mode via `backgroundremover-server`, which exposes the removal functionality through a Flask API, allowing integration into web applications and networked workflows without invoking the CLI directly.

## Development status and model selection

BackgroundRemover is actively maintained. The last push was on 2026-07-10, and the most recent release v0.4.5 was published on 2026-07-10T01:23:27Z. Earlier releases include v0.4.4 from 2026-06-09 and v0.4.1 from 2026-02-17. The tool is licensed under the MIT license.

Model selection is the main way to trade speed for accuracy. The u2net model is the default and handles general objects well. The u2net_human_seg model is optimized for human subjects and produces better results on portraits and people. The u2netp model is fastest but least accurate, useful for batch processing where speed matters more than perfect edges. Each model is downloaded on first run if not already cached locally.

BackgroundRemover can also output only the binary mask (segmentation map) via the `-om` flag, useful if you want to use the mask in downstream tools. The project includes a requirements.txt listing all dependencies: numpy, scikit-image, torch, torchvision, tqdm, requests, scipy, pymatting, filetype, more_itertools, moviepy, Pillow, pillow-heif, ffmpeg-python, and flask.

## Conclusion

Use BackgroundRemover if you need to batch-process images or videos for background removal from the command line, or integrate it into a pipeline. Skip it if you need a GUI or real-time interactive editing. Start by installing from PyPI with pip, then try it on a single image before processing a folder or video.

## FAQ

### How do I use BackgroundRemover?

Point BackgroundRemover at an image or video file with the -i flag and specify an output file with -o. For folders, use -if and -of flags. Example: `backgroundremover -i image.jpg -o output.png`.

### What is BackgroundRemover?

BackgroundRemover is a command-line tool that uses U2Net AI to detect and remove backgrounds from images and videos. It supports GPU acceleration and can replace backgrounds with custom colors or images.

### Does BackgroundRemover work on video files?

Yes. BackgroundRemover supports background removal from video files using the same command syntax as images. It requires ffmpeg and adequate system resources for video processing.

### What image formats does BackgroundRemover support?

BackgroundRemover supports JPG, JPEG, PNG, HEIC and HEIF image formats. HEIC/HEIF support requires the pillow-heif package to be installed.

### Can BackgroundRemover run on GPU?

Yes. BackgroundRemover automatically detects and uses GPU if available via CUDA, providing 5-10x speed improvements over CPU. Verify GPU usage with `python3 -c "import torch; print(torch.cuda.is_available())"`.

## Sources

- [License: MIT](https://github.com/nadermx/backgroundremover/blob/main/LICENSE)
- [nadermx/backgroundremover on GitHub](https://github.com/nadermx/backgroundremover)
- [Project website](https://backgroundremoverai.com)
- [README](https://github.com/nadermx/backgroundremover/blob/main/README.md)
- [Releases](https://github.com/nadermx/backgroundremover/releases)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/nadermx-backgroundremover