Registry / ai-ml / transparent-background

transparent-background

JSON →
library1.3.4pypypi✓ verified 86d ago

Transparent-background is a Python library that leverages InSPyReNet (ACCV 2022) to remove backgrounds from images and videos, making them transparent. It supports various output modes, including RGBA, green screen, blur, and overlay. The library is actively maintained, with frequent updates addressing performance, dependencies, and new features.

pip install transparent-background
INSTALL
IMPORT
SIG · TRANSPARENT-BACKGR
T
transparent-background
ai-mlpythonv1.3.4
Install
Import
Disk
Pass rate
0/ 10
Env Coverage0 / 10
glibc
3.93.13
musl
3.93.13
Install & Compatibility
Where this runs
tested against v1.3.4 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
musl
glibc
py 3.10
✕ build_error
4/16 runs
py 3.11
✕ build_error
6/16 runs
py 3.12
✕ build_error
12/16 runs
py 3.13
✕ build_error
12/16 runs
py 3.9
✕ build_error
✕ timeout
Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

Remover
from transparent_background import Remover
Image
from PIL import Image
import Image
Pillow's Image module is typically imported as `PIL.Image`.

This example demonstrates how to use `transparent-background` to remove the background from an image. It creates a dummy image, processes it using the `Remover` class to achieve a transparent background, and then saves the result. The `device` parameter can be set to 'cuda' for GPU acceleration if PyTorch with CUDA is installed.

import os from PIL import Image from transparent_background import Remover # Create a dummy image for demonstration try: img = Image.new('RGB', (200, 200), color = 'red') # Add a white circle in the middle from PIL import ImageDraw draw = ImageDraw.Draw(img) draw.ellipse((50, 50, 150, 150), fill='white', outline='white') input_image_path = 'input_image.png' output_image_path = 'output_transparent_image.png' img.save(input_image_path) print(f"Dummy image saved to {input_image_path}") # Initialize the Remover (downloads model checkpoint on first run) # Consider setting TRANSPARENT_BACKGROUND_FILE_PATH if default home directory is an issue remover = Remover(fast=False, jit=False, device='cpu') # 'cuda' for GPU if available # Load an image img = Image.open(input_image_path) # Process the image to remove background # 'bg_color=(0, 0, 0, 0)' ensures a fully transparent background for RGBA out = remover.process(img, type='rgba', threshold=0.5, bg_color=(0,0,0,0)) # Save the output image out.save(output_image_path) print(f"Processed image saved to {output_image_path}") # Clean up dummy image os.remove(input_image_path) os.remove(output_image_path) print("Cleaned up dummy images.") except Exception as e: print(f"An error occurred: {e}") print("Please ensure PyTorch is installed correctly for your system (e.g., with CUDA support if desired).") print("You might also need to install optional dependencies like `flet` or `pyvirtualcam` if using GUI/webcam features.")
transparent-background --version
Debug
Known issues
breakingThe `flet` (GUI) dependency was moved to an extra (`[gui]`) due to import errors with `flet` versions >= 0.25.0.
fix
Install with `pip install transparent-background[gui]` if you need GUI functionality.
affects: >=1.3.4
deprecatedThe `--jit` command-line option is deprecated. Its functionality (for stability) has been replaced by the `--resize` option.
fix
Remove `--jit` and use `--resize static` for stable output. For Python API, `remover = Remover(jit=False, resize='static')`.
affects: >=1.2.7 (transition started), fully deprecated later
breakingThe `gdown` module for checkpoint downloading was replaced by `wget` due to instability. This migration required users to manually remove the `config.yaml` file from `$HOME/.transparent_background`.
fix
Before upgrading to >=1.2.12, delete `config.yaml` from `$HOME/.transparent_background`. If issues persist, manually download `.pth` checkpoint files from GitHub releases and place them in the directory.
affects: >=1.2.12
deprecatedThe `--fast` command-line argument is deprecated and has been replaced by the `--mode` argument.
fix
Use `--mode fast` instead of `--fast`. For Python API, use `remover = Remover(mode='fast')`.
affects: >=1.2.7 (transition started), fully deprecated later
gotchaThe 'rgba' output type (generating an alpha map) is not supported for video or webcam input due to underlying technical limitations.
fix
For video/webcam input, use other output types like 'green', 'blur', or 'overlay', or process frames individually and apply custom alpha blending.
affects: All versions
gotchaThe default configuration file directory (`~/.transparent-background/config.yaml`) might be inaccessible on non-PC systems.
fix
Set the `TRANSPARENT_BACKGROUND_FILE_PATH` environment variable to a writable directory where the config file can be stored (e.g., `os.environ['TRANSPARENT_BACKGROUND_FILE_PATH'] = '/tmp/transparent-background-config.yaml'`).
affects: All versions
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'flet'
The GUI dependency `flet` is no longer part of the default installation.
fix
Install the library with the GUI extra: `pip install transparent-background[gui]`.
Failed to download checkpoint file. Please check your internet connection or try again later.
Issues with downloading pre-trained model checkpoints, potentially due to `gdown` instability (older versions) or network problems.
fix
Ensure a stable internet connection. For versions >=1.2.12, make sure `config.yaml` is removed from `$HOME/.transparent_background`. If problems persist, manually download the `.pth` checkpoint file from the GitHub releases page and place it in `$HOME/.transparent_background`.
ModuleNotFoundError: No module named 'pyvirtualcam'
Webcam functionality requires an optional dependency that is no longer installed by default.
fix
Install the library with the webcam extra: `pip install transparent-background[webcam]`.
AttributeError: 'Remover' object has no attribute 'process_video' (or similar for webcam, when using rgba)
The `rgba` output type is not supported for video or webcam inputs, as stated in the documentation.
fix
When processing video or webcam streams, choose a different output `type` such as `'green'`, `'blur'`, or `'overlay'`. For example, `remover.process(frame, type='green')`.
Upgrade
Version history
1.3.4latest on PyPI · released May 14, 2025
Audit
Dependencies
fletoptionalOptional, for the graphical user interface (`[gui]` extra).
pyvirtualcamoptionalOptional, for webcam input support (`[webcam]` extra).
PillowrequiredRequired for image manipulation (e.g., `PIL.Image.open`).
torchrequiredCore dependency for the underlying InSPyReNet deep learning model.
pymattingoptionalOptional, for GPU-accelerated foreground color estimation during RGBA output. Requires CuPy or pyopencl for GPU acceleration.
cupyoptionalOptional, for GPU acceleration with pymatting, if CUDA is available.
pyopencloptionalOptional, for GPU acceleration with pymatting, as an alternative to CuPy.
Agent activity
50 hits · last 30 days
node
44
Amazon
1
OpenAI (training)
1
Resources
transparent-background — pip install transparent-background · libregistry