Nanobanana Cleaner is a lightweight and fast Python tool for removing backgrounds from AI-generated images and adding transparency channels.
Have you ever encountered this situation: AI-generated images look great, but when you insert them into documents, PPTs, or web pages, you find that the background is not pure white, or there's no transparency channel at all?
Common Problems:
- ❌ Background has slight yellowish or grayish tones
- ❌ PNG format but no transparency channel
- ❌ Causes occlusion when pasted elsewhere
- ❌ Light blue, light orange, and other colored backgrounds are accidentally deleted
Nanobanana Cleaner's Solution:
- ✅ Intelligently identify and remove background colors
- ✅ Automatically add transparency channels
- ✅ Protect colored background elements from accidental deletion
- ✅ Edge smoothing processing, eliminate jagged edges
- ✅ Support batch processing, improve efficiency
| Feature | Description |
|---|---|
| 🎨 Smart Background Detection | Supports white, black, and custom color backgrounds |
| 🛡️ Color Protection Mechanism | Automatically protects light blue, light orange, and other colored background elements |
| ✨ Edge Smoothing Processing | Adjustable feathering effect, eliminates jagged edges |
| 🔍 Edge Detection Protection | Sobel operator protects subject boundaries from accidental deletion |
| 🧹 Morphological Optimization | Automatically removes noise and fills holes |
| 🚀 Batch Processing Capability | Process hundreds of images at once |
| 🎯 Auto Background Detection | K-means clustering automatically identifies background color |
- CIELAB Color Space: Color difference calculation that better matches human perception
- Sobel Edge Detection: Accurately identify and protect subject boundaries
- Gaussian Blur Feathering: Smooth edges, improve visual quality
- K-means Auto Detection: Intelligently identify main background color of images
- Morphological Operations: Opening removes noise, closing fills holes
| Before | After |
|---|---|
 |
 |
Left image has a light gray background, right image has background removed with transparent channel
- Python 3.10 or higher
- NumPy >= 2.2.6
- Pillow >= 12.0.0
- SciPy >= 1.10.0
- scikit-learn >= 1.3.0
git clone https://github.com/MRT-8/Nanobanana-Cleaner.git
cd Nanobanana-Cleaner
uv syncgit clone https://github.com/MRT-8/Nanobanana-Cleaner.git
cd Nanobanana-Cleaner
pip install numpy pillow scipy scikit-learn# Process a single image (all enhanced features automatically enabled)
python cleaner.py -i your_image.png
# Output: your_image_cleaned.pngIt's that simple! The tool will automatically:
- Detect background color
- Apply color protection
- Smooth edges
- Output high-quality PNG
# Process multiple images
python cleaner.py -i img1.png img2.png img3.png
# Process entire directory
python cleaner.py -i /path/to/images/
# Output saved to /path/to/images/output/# Remove black background
python cleaner.py -i dark_image.png --background 0,0,0
# Auto-detect background color
python cleaner.py -i unknown_bg.png --auto-detect-bg
# More aggressive background removal
python cleaner.py -i image.png --transparent 0.05| Parameter | Default | Description |
|---|---|---|
-i, --input |
Required | Input image path or directory |
-o, --output |
Auto-generated | Output image path |
--transparent |
0.1 | Transparency threshold (0-1) |
--opaque |
1.0 | Opacity threshold (0-1) |
--background |
255,255,255 | Background color (R,G,B) |
| Parameter | Default | Description |
|---|---|---|
--feather |
2 | Edge feathering radius (pixels) |
--no-lab |
False | Use RGB color space |
--no-edge-protection |
False | Disable edge protection |
--no-morphological |
False | Disable morphological optimization |
--no-color-protection |
False | Disable color protection |
--auto-detect-bg |
False | Auto-detect background color |
# Color protection is enabled by default, automatically preserving light blue, light orange elements
python cleaner.py -i diagram.pngUse Case: Technical diagrams, flowcharts, images with decorative borders
# Increase feathering radius
python cleaner.py -i portrait.png --feather 4Use Case: Portrait photos, images that need soft edges
# Disable color protection for cleaner background
python cleaner.py -i pure_white.png --no-color-protectionUse Case: Pure white background product images, icons
# Let the tool auto-detect background color
python cleaner.py -i mystery.png --auto-detect-bgUse Case: Images with uncertain background color
Add cleaner to your system path for use anywhere:
Zsh users:
echo 'alias cleaner="python /path/to/Nanobanana-Cleaner/cleaner.py"' >> ~/.zshrc
source ~/.zshrcBash users:
echo 'alias cleaner="python /path/to/Nanobanana-Cleaner/cleaner.py"' >> ~/.bashrc
source ~/.bashrcNow you can use it directly:
cleaner -i ~/Downloads/image.pngNanobanana Cleaner uses advanced image processing pipeline:
Image Loading → Color Space Conversion → Color Distance Calculation → Color Protection
↓
Edge Detection → Transparency Application → Morphological Optimization → Edge Feathering
↓
High Quality Output
- Color difference calculation that better matches human perception
- Provides perceptually uniform color distance
- Accurately identify subject boundaries
- Protect subject from accidental deletion
- Smooth edges, eliminate jagged lines
- Adjustable feathering radius
- Automatically identify main background color of images
- Suitable for images with unknown background color
- Opening: Remove small noise
- Closing: Fill small holes
- ✅ AI-generated images (Gemini, GPT, Claude, etc.)
- ✅ Technical diagrams, flowcharts
- ✅ Product images, product photos
- ✅ Portraits, avatars
- ✅ Icons, logos
- ✅ Any images that need transparent backgrounds
Contributions, issue reporting, and suggestions are welcome!
This project is licensed under the MIT License - see the LICENSE file for details
Special thanks to Melmaphother/Nanobanana-Peel for the inspiration. Nanobanana Cleaner has been enhanced with additional features and algorithm optimizations on top of their excellent work.
Made with ❤️ | Nanobanana Cleaner