BackgroundRemover

<img alt="background remover video" src="https://raw.githubusercontent.com/nadermx/backgroundremover/main/examplefiles/backgroundremoverprocessed.gif" height="200" /><br> BackgroundRemover is a command line tool to remove background from image and video using AI, made by nadermx to power https://BackgroundRemoverAI.com. If you wonder why it was made read this short blog post.<br>

Requirements

• python >= 3.6

• python3.6-dev #or what ever version of python you use

• torch and torchvision stable version (https://pytorch.org)

• ffmpeg 4.4+

• To clarify, you must install both python and whatever dev version of python you installed. IE; python3.10-dev with python3.10 or python3.8-dev with python3.8

How to install torch and ffmpeg

Go to https://pytorch.org and scroll down to INSTALL PYTORCH section and follow the instructions.

For CPU-only (default):

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

For GPU (CUDA) support:

# For CUDA 11.8
pip3 install torch torchvision --index-url https://download.pytorch.org/whl/cu118

# For CUDA 12.1
pip3 install torch torchvision --index-url https://download.pytorch.org/whl/cu121

Visit https://pytorch.org/get-started/locally/ to find the correct command for your CUDA version.

To install ffmpeg and python-dev:

sudo apt install ffmpeg python3.6-dev

Installation

To Install backgroundremover, install it from pypi

pip install --upgrade pip
pip install backgroundremover

Please note that when you first run the program, it will check to see if you have the u2net models, if you do not, it will pull them from this repo

It is also possible to run this without installing it via pip, just clone the git to local start a virtual env and install requirements and run

python -m backgroundremover.cmd.cli -i "video.mp4" -mk -o "output.mov"

and for windows

python.exe -m backgroundremover.cmd.cli -i "video.mp4" -mk -o "output.mov"

Installation using Docker

git clone https://github.com/nadermx/backgroundremover.git
cd backgroundremover
docker build -t bgremover .
# Basic usage (models will be downloaded on each run)
alias backgroundremover='docker run -it --rm -v "$(pwd):/tmp" bgremover:latest'

# Recommended: Persist models between runs to avoid re-downloading
mkdir -p ~/.u2net
alias backgroundremover='docker run -it --rm -v "$(pwd):/tmp" -v "$HOME/.u2net:/root/.u2net" bgremover:latest'

# For video processing: Increase shared memory to avoid multiprocessing errors
alias backgroundremover='docker run -it --rm --shm-size=2g -v "$(pwd):/tmp" -v "$HOME/.u2net:/root/.u2net" bgremover:latest'

Note for Docker video processing: Video processing uses multiprocessing which requires adequate shared memory. If you encounter errors like OSError: [Errno 95] Operation not supported, use --shm-size=2g (or higher) or --ipc=host when running the container.

GPU Acceleration

BackgroundRemover automatically detects and uses your GPU if available, which provides significant speed improvements (typically 5-10x faster than CPU).

To verify GPU is being used:

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')"

Troubleshooting GPU issues:

1. GPU not detected: Ensure you installed the CUDA-compatible version of PyTorch (see installation instructions above)
2. Out of memory errors: Reduce GPU batch size with -gb 1 flag
3. Slow performance on CPU: Install CUDA-compatible PyTorch for GPU acceleration
4. CUDA version mismatch: Match your PyTorch CUDA version with your system's CUDA installation

The tool will automatically fall back to CPU if GPU is not available or encounters errors.

Usage as a cli

Image

Remove the background from a local file image

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

Supported image formats: .jpg, .jpeg, .png, .heic, .heif (HEIC/HEIF support requires pillow-heif)

Process all images in a folder

You can now remove backgrounds from all supported image or video files in a folder using the --input-folder (-if) option. You can also optionally set an output folder using --output-folder (-of). If --output-folder is not provided, the outputs will be saved in the same input folder, prefixed with output_.

Example: Folder of Images

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

This will process all .jpg, .jpeg, .png, .heic, and .heif images in the folder and save the results to the output folder.

Advance usage for image background removal

Alpha Matting for Better Edge Quality:

By default, backgroundremover produces soft, natural edges. For some use cases (like cartoons, graphics, or sharp-edged objects), you may want sharper edges or better edge refinement.

# Enable alpha matting for refined edges
backgroundremover -i "/path/to/image.jpeg" -a -o "output.png"

# Adjust erosion size for sharper/softer edges (default: 10)
# Smaller values (1-5) = sharper, harder edges (good for cartoons/graphics)
# Larger values (15-25) = softer, more natural edges (good for portraits)
backgroundremover -i "/path/to/image.jpeg" -a -ae 5 -o "output.png"

Alpha matting parameters:

• -a - Enable alpha matting
• -af - Foreground threshold (default: 240)
• -ab - Background threshold (default: 10)
• -ae - Erosion size (1-25, default: 10) - controls edge sharpness
• -az - Base size (default: 1000) - affects processing resolution

Change the model for different subjects:

# For humans/people - most accurate for human subjects
backgroundremover -i "/path/to/image.jpeg" -m "u2net_human_seg" -o "output.png"

# For general objects - good all-around model (default)
backgroundremover -i "/path/to/image.jpeg" -m "u2net" -o "output.png"

# Faster processing - lower accuracy but quicker
backgroundremover -i "/path/to/image.jpeg" -m "u2netp" -o "output.png"

Output only the mask (binary mask/matte)

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

Replace background with a custom color

# Replace with red background
backgroundremover -i "/path/to/image.jpeg" -bc "255,0,0" -o "output.png"

# Replace with green background
backgroundremover -i "/path/to/image.jpeg" -bc "0,255,0" -o "output.png"

# Replace with blue background
backgroundremover -i "/path/to/image.jpeg" -bc "0,0,255" -o "output.png"

Replace background with a custom image

# Replace background with another image
backgroundremover -i "/path/to/image.jpeg" -bi "/path/to/background.jpg" -o "output.png"

Use with pipes (stdin/stdout)

You can use backgroundremover in Unix pipelines by reading from stdin and writing to stdout:

# Read from stdin, write to stdout
cat input.jpg | backgroundremover > output.png

# Use with other tools in a pipeline
curl https://example.com/image.jpg | backgroundremover | convert - -resize 50% smaller.png

# Equivalent explicit syntax
backgroundremover -i - -o - < input.jpg > output.png

Note: Pipe mode assumes image input (not video).

Run as HTTP API Server

You can run backgroundremover as an HTTP API server:

# Start server on default port 5000
backgroundremover-server

# Specify custom host and port
backgroundremover-server --addr 0.0.0.0 --port 8080

API Usage:

# Upload image via POST
curl -X POST -F "file=@image.jpg" http://localhost:5000/ -o output.png

# Process from URL via GET
curl "http://localhost:5000/?url=https://example.com/image.jpg" -o output.png

# With alpha matting
curl "http://localhost:5000/?url=https://example.com/image.jpg&a=true&af=240" -o output.png

# Choose model
curl "http://localhost:5000/?url=https://example.com/image.jpg&model=u2net_human_seg" -o output.png

Parameters:

• a - Enable alpha matting
• af - Alpha matting foreground threshold (default: 240)
• ab - Alpha matting background threshold (default: 10)
• ae - Alpha matting erosion size (default: 10)
• az - Alpha matting base size (default: 1000)
• model - Model choice: u2net, u2netp, or u2net_human_seg

Video

remove background from video and make transparent mov

backgroundremover -i "/path/to/video.mp4" -tv -o "output.mov"

Process all videos in a folder

You can now remove backgrounds from all supported image or video files in a folder using the --input-folder (-if) option. You can also optionally set an output folder using --output-folder (-of). If --output-folder is not provided, the outputs will be saved in the same input folder, prefixed with output_.

Example: Folder of Videos to Transparent .mov

backgroundremover -if "/path/to/video-folder" -of "/path/to/output-folder" -tv

You can also combine additional options:

backgroundremover -if "videos" -of "processed" -m "u2net_human_seg" -fr 30 -tv

• Uses the u2net_human_seg model
• Overrides video framerate to 30 fps
• Outputs transparent .mov files into the processed/ folder
• Supported video formats: .mp4, .mov, .webm, .ogg, .gif
• Output files will be named like output_filename.ext in the output folder

remove background from local video and overlay it over other video

backgroundremover -i "/path/to/video.mp4" -tov -bv "/path/to/background_video.mp4" -o "output.mov"

remove background from local video and overlay it over an