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
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.fixInstall 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.fixRemove `--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`.fixBefore 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.fixUse `--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.fixFor 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.fixSet 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.
fixInstall 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.
fixEnsure 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.
fixInstall 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.
fixWhen 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.