YAML Metadata Warning:empty or missing yaml metadata in repo card

Check out the documentation for more information.

Background Remover - Full Stack Application

A production-ready full-stack application for removing backgrounds from images and videos using the library.

Installation

Prerequisites

Python 3.10 or higher
FFmpeg (for video processing)

Note: FFmpeg must be installed separately on your system:

Ubuntu/Debian: sudo apt-get install ffmpeg
macOS: brew install ffmpeg
Windows: Download from ffmpeg.org

Install from PyPI

The recommended way to install the Background Remover Model is using a virtual environment:

Step 1: Install Python venv (if not already installed)

Ubuntu/Debian:

sudo apt install python3-venv -y

macOS:

# venv is usually pre-installed with Python
python3 --version

Windows:

# venv is usually pre-installed with Python
python --version

Step 2: Create Virtual Environment

python3 -m venv bgremover-env

Step 3: Activate Virtual Environment

Linux/macOS:

source bgremover-env/bin/activate

Windows:

bgremover-env\Scripts\activate

Step 4: Install the Package

pip install background-remover-model

This will install the package and all its dependencies. After installation, you can import and use the API in your Python projects.

Step 5: Deactivate Virtual Environment (when done)

deactivate

Note: Always activate your virtual environment before using the package. You can run Python scripts inside the activated environment.

Quick Start (After Installation)

Important: Make sure your virtual environment is activated before running the server:

# Activate virtual environment (if not already activated)
source bgremover-env/bin/activate  # Linux/macOS
# or
bgremover-env\Scripts\activate      # Windows

Once installed and activated, you can run the API server:

# Run the FastAPI server
uvicorn app.main:app --host 0.0.0.0 --port 8000

Or use it as a Python package in your code:

from app.main import app
from app.routers import image_router, video_router

# The FastAPI app is ready to use
# Access API docs at http://localhost:8000/docs

Features

🖼️ Image Background Removal: Remove backgrounds from images with various models
🎥 Video Background Removal: Process videos to remove backgrounds
🎨 Advanced Options: Alpha matting, custom background colors, background images
📊 Real-time Processing: Visual feedback during processing
🎯 Before/After Preview: Side-by-side comparison of original and processed files
📥 Easy Download: One-click download of processed files

Tech Stack

Backend

Python 3.10+
FastAPI
backgroundremover
PyTorch (CPU)
FFmpeg
Celery (optional for async processing)
Redis (optional, for Celery)

Frontend

React 18
Vite
TailwindCSS
Axios

Project Structure

.
├── backend/
│   ├── app/
│   │   ├── main.py              # FastAPI application
│   │   ├── routers/             # API route handlers
│   │   │   ├── image_router.py
│   │   │   └── video_router.py
│   │   ├── services/            # Business logic
│   │   │   └── background_remover.py
│   │   ├── utils/               # Utility functions
│   │   │   └── file_cleanup.py
│   │   └── models/              # Pydantic models
│   │       └── schemas.py
│   ├── requirements.txt
│   └── Dockerfile
├── frontend/
│   ├── src/
│   │   ├── components/          # React components
│   │   │   ├── FileUploader.jsx
│   │   │   ├── OptionsPanel.jsx
│   │   │   └── ResultViewer.jsx
│   │   ├── App.jsx
│   │   ├── main.jsx
│   │   └── index.css
│   ├── package.json
│   ├── vite.config.js
│   ├── tailwind.config.js
│   ├── nginx.conf
│   └── Dockerfile
├── docker-compose.yml
├── .env.example
└── README.md

Quick Start

Option 1: Install from PyPI (Recommended for API Usage)

Set up virtual environment (see Installation section above)

# Install venv if needed
sudo apt install python3-venv -y  # Ubuntu/Debian

# Create and activate virtual environment
python3 -m venv bgremover-env
source bgremover-env/bin/activate

Install the package
```
pip install background-remover-model
```
Install FFmpeg (required for video processing)
- Ubuntu/Debian: sudo apt-get install ffmpeg
- macOS: brew install ffmpeg
- Windows: Download from ffmpeg.org

Run the API server

uvicorn app.main:app --host 0.0.0.0 --port 8000

Access the API
- API: http://localhost:8000
- API Documentation: http://localhost:8000/docs
Deactivate virtual environment (when done)
```
deactivate
```

Option 2: Using Docker (Full Stack Application)

Prerequisites

Docker and Docker Compose
(Optional) Node.js 18+ and Python 3.10+ for local development

Clone or navigate to the project directory
Start the application
```
docker-compose up --build
```
Access the application
- Frontend: http://localhost
- Backend API: http://localhost:8000
- API Documentation: http://localhost:8000/docs

Local Development

Backend

Navigate to backend directory
```
cd backend
```

Create virtual environment

python3 -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

Install dependencies
```
pip install -r requirements.txt
```
Install FFmpeg (if not already installed)
- Ubuntu/Debian: sudo apt-get install ffmpeg
- macOS: brew install ffmpeg
- Windows: Download from ffmpeg.org

Run the server

uvicorn app.main:app --reload --host 0.0.0.0 --port 8000

Frontend

Navigate to frontend directory
```
cd frontend
```
Install dependencies
```
npm install
```
Run development server
```
npm run dev
```
Access the app
- Frontend: http://localhost:5173

API Endpoints

POST /remove-image

Remove background from an uploaded image.

Request:

file (multipart/form-data): Image file
model (optional): Model to use (u2net, u2netp, u2net_human_seg)
alpha_matting (optional): Enable alpha matting (boolean)
alpha_matting_foreground_threshold (optional): Foreground threshold (0-255)
alpha_matting_background_threshold (optional): Background threshold (0-255)
alpha_matting_erode_structure_size (optional): Erode structure size
alpha_matting_base_size (optional): Base size for alpha matting
background_color (optional): Hex color code (e.g., "#FF0000")
background_image (optional): Background image file

Response:

Processed image file (PNG)

POST /remove-video

Remove background from an uploaded video.

Request:

file (multipart/form-data): Video file
model (optional): Model to use
tv (optional): TV mode flag (boolean)
mk (optional): Masks only flag (boolean)
tov (optional): Transparent output video flag (boolean)
toi (optional): Transparent output images flag (boolean)
gb (optional): Green background flag (boolean)
wn (optional): White background flag (boolean)
fr (optional): Frame rate (float)
fl (optional): Frame limit (float)
background_color (optional): Hex color code
background_image (optional): Background image file

Response:

Processed video file (MP4)

GET /health

Health check endpoint.

Response:

{
  "status": "healthy"
}

Usage

Upload a file: Drag and drop or click to browse for an image or video
Configure options: Select model, enable alpha matting, set background color/image
Process: Click "Remove Background" to start processing
View results: See side-by-side comparison of original and processed files
Download: Click "Download Result" to save the processed file

Models

u2net: Default model, good general-purpose performance
u2netp: Lightweight model, faster processing
u2net_human_seg: Optimized for human segmentation

Advanced Options

Alpha Matting

Improves edge quality for better results, especially for fine details like hair.

Background Replacement

Background Color: Replace background with a solid color (hex format)
Background Image: Replace background with another image

Video Options

TV Mode (-tv): Optimize for TV/video content
Masks Only (-mk): Generate masks only
Transparent Output: Create transparent backgrounds
Frame Rate/Limit: Control video processing parameters

File Cleanup

The application automatically cleans up temporary files older than 24 hours. You can manually trigger cleanup by calling the cleanup service.

Troubleshooting

Backend Issues

FFmpeg not found
- Ensure FFmpeg is installed in the Docker container or system
- Check Dockerfile includes FFmpeg installation
Out of memory
- Large videos may require more memory
- Consider processing smaller files or increasing Docker memory limits
Processing fails
- Check file format is supported
- Verify model files are downloaded (first run may download models)

Frontend Issues

CORS errors
- Update CORS_ORIGINS in .env file
- Ensure backend is running and accessible
Upload fails
- Check file size limits (configured in nginx.conf)
- Verify backend is running

Development Scripts

Backend

# Start backend
cd backend
uvicorn app.main:app --reload

# Run cleanup
python -m app.utils.file_cleanup

Frontend

# Start dev server
cd frontend
npm run dev

# Build for production
npm run build

# Preview production build
npm run preview

Docker Commands

# Build and start all services
docker-compose up --build

# Start in background
docker-compose up -d

# View logs
docker-compose logs -f

# Stop services
docker-compose down

# Rebuild specific service
docker-compose build backend
docker-compose up -d backend

Environment Variables

Copy .env.example to .env and configure:

CORS_ORIGINS: Allowed CORS origins (comma-separated)
REDIS_URL: Redis connection URL (if using Celery)
CELERY_BROKER_URL: Celery broker URL
CELERY_RESULT_BACKEND: Celery result backend URL

License

This project uses the backgroundremover library. Please refer to the backgroundremover license for details.

Contributing

Fork the repository
Create a feature branch
Make your changes
Submit a pull request

Support

For issues related to:

backgroundremover library: GitHub Issues
This application: Open an issue in this repository

Acknowledgments

backgroundremover - The core library for background removal
FastAPI - Modern Python web framework
React & Vite - Frontend framework and build tool

Downloads last month: -; Downloads are not tracked for this model. How to track

Inference Providers NEW

This model isn't deployed by any Inference Provider. 🙋 Ask for provider support