{"id":7805,"library":"transparent-background","title":"Transparent Background Image/Video Remover","description":"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.","status":"active","version":"1.3.4","language":"en","source_language":"en","source_url":"https://github.com/plemeri/transparent-background","tags":["image-processing","background-removal","deep-learning","computer-vision","ai","video-processing"],"install":[{"cmd":"pip install transparent-background","lang":"bash","label":"Base installation"},{"cmd":"pip install transparent-background[gui]","lang":"bash","label":"With GUI support (requires flet)"},{"cmd":"pip install transparent-background[webcam]","lang":"bash","label":"With webcam support (requires pyvirtualcam)"},{"cmd":"pip install --extra-index-url https://download.pytorch.org/whl/cu118 transparent-background","lang":"bash","label":"For CUDA-enabled PyTorch (replace cu118 with your version)"}],"dependencies":[{"reason":"Optional, for the graphical user interface (`[gui]` extra).","package":"flet","optional":true},{"reason":"Optional, for webcam input support (`[webcam]` extra).","package":"pyvirtualcam","optional":true},{"reason":"Required for image manipulation (e.g., `PIL.Image.open`).","package":"Pillow","optional":false},{"reason":"Core dependency for the underlying InSPyReNet deep learning model.","package":"torch","optional":false},{"reason":"Optional, for GPU-accelerated foreground color estimation during RGBA output. Requires CuPy or pyopencl for GPU acceleration.","package":"pymatting","optional":true},{"reason":"Optional, for GPU acceleration with pymatting, if CUDA is available.","package":"cupy","optional":true},{"reason":"Optional, for GPU acceleration with pymatting, as an alternative to CuPy.","package":"pyopencl","optional":true}],"imports":[{"symbol":"Remover","correct":"from transparent_background import Remover"},{"note":"Pillow's Image module is typically imported as `PIL.Image`.","wrong":"import Image","symbol":"Image","correct":"from PIL import Image"}],"quickstart":{"code":"import os\nfrom PIL import Image\nfrom transparent_background import Remover\n\n# Create a dummy image for demonstration\ntry:\n    img = Image.new('RGB', (200, 200), color = 'red')\n    # Add a white circle in the middle\n    from PIL import ImageDraw\n    draw = ImageDraw.Draw(img)\n    draw.ellipse((50, 50, 150, 150), fill='white', outline='white')\n    input_image_path = 'input_image.png'\n    output_image_path = 'output_transparent_image.png'\n    img.save(input_image_path)\n    print(f\"Dummy image saved to {input_image_path}\")\n\n    # Initialize the Remover (downloads model checkpoint on first run)\n    # Consider setting TRANSPARENT_BACKGROUND_FILE_PATH if default home directory is an issue\n    remover = Remover(fast=False, jit=False, device='cpu') # 'cuda' for GPU if available\n\n    # Load an image\n    img = Image.open(input_image_path)\n\n    # Process the image to remove background\n    # 'bg_color=(0, 0, 0, 0)' ensures a fully transparent background for RGBA\n    out = remover.process(img, type='rgba', threshold=0.5, bg_color=(0,0,0,0))\n\n    # Save the output image\n    out.save(output_image_path)\n    print(f\"Processed image saved to {output_image_path}\")\n\n    # Clean up dummy image\n    os.remove(input_image_path)\n    os.remove(output_image_path)\n    print(\"Cleaned up dummy images.\")\n\nexcept Exception as e:\n    print(f\"An error occurred: {e}\")\n    print(\"Please ensure PyTorch is installed correctly for your system (e.g., with CUDA support if desired).\")\n    print(\"You might also need to install optional dependencies like `flet` or `pyvirtualcam` if using GUI/webcam features.\")\n","lang":"python","description":"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."},"warnings":[{"fix":"Install with `pip install transparent-background[gui]` if you need GUI functionality.","message":"The `flet` (GUI) dependency was moved to an extra (`[gui]`) due to import errors with `flet` versions >= 0.25.0.","severity":"breaking","affected_versions":">=1.3.4"},{"fix":"Remove `--jit` and use `--resize static` for stable output. For Python API, `remover = Remover(jit=False, resize='static')`.","message":"The `--jit` command-line option is deprecated. Its functionality (for stability) has been replaced by the `--resize` option.","severity":"deprecated","affected_versions":">=1.2.7 (transition started), fully deprecated later"},{"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.","message":"The `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`.","severity":"breaking","affected_versions":">=1.2.12"},{"fix":"Use `--mode fast` instead of `--fast`. For Python API, use `remover = Remover(mode='fast')`.","message":"The `--fast` command-line argument is deprecated and has been replaced by the `--mode` argument.","severity":"deprecated","affected_versions":">=1.2.7 (transition started), fully deprecated later"},{"fix":"For video/webcam input, use other output types like 'green', 'blur', or 'overlay', or process frames individually and apply custom alpha blending.","message":"The 'rgba' output type (generating an alpha map) is not supported for video or webcam input due to underlying technical limitations.","severity":"gotcha","affected_versions":"All versions"},{"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'`).","message":"The default configuration file directory (`~/.transparent-background/config.yaml`) might be inaccessible on non-PC systems.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-16T00:00:00.000Z","next_check":"2026-07-15T00:00:00.000Z","problems":[{"fix":"Install the library with the GUI extra: `pip install transparent-background[gui]`.","cause":"The GUI dependency `flet` is no longer part of the default installation.","error":"ModuleNotFoundError: No module named 'flet'"},{"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`.","cause":"Issues with downloading pre-trained model checkpoints, potentially due to `gdown` instability (older versions) or network problems.","error":"Failed to download checkpoint file. Please check your internet connection or try again later."},{"fix":"Install the library with the webcam extra: `pip install transparent-background[webcam]`.","cause":"Webcam functionality requires an optional dependency that is no longer installed by default.","error":"ModuleNotFoundError: No module named 'pyvirtualcam'"},{"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')`.","cause":"The `rgba` output type is not supported for video or webcam inputs, as stated in the documentation.","error":"AttributeError: 'Remover' object has no attribute 'process_video' (or similar for webcam, when using rgba)"}]}