Install & Compatibility
Where this runs
tested against v2.0.81 · 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
✕ timeout
py 3.11
✕ build_error
✕ timeout
py 3.12
✕ build_error
✕ timeout
py 3.13
✕ build_error
3/4 runs
py 3.9
✕ build_error
1/4 runs
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
remove
✓ from rembg import remove
The primary function to remove backgrounds.
new_session
✓ from rembg import new_session
Creates an inference session for a specific model. Important for performance when processing multiple images.
Image
✓ from PIL import Image
Often used with `rembg` for opening and saving images.
This quickstart demonstrates how to use `rembg` to remove the background from an image. It highlights the use of `new_session` for efficiency and assumes `PIL` for image handling. For a real scenario, replace the dummy image creation with loading from a file (e.g., `Image.open('input.png')`).
from PIL import Image
from rembg import remove, new_session
# Create a session to improve performance for multiple images
session = new_session()
# Example: Load an image from a dummy source or local path
# For a real application, replace this with actual image loading
# For demonstration, we'll create a blank image
# In a real scenario, you'd use Image.open('path/to/your/image.png')
try:
# Simulate loading an image (replace with actual image path)
input_image = Image.new('RGBA', (200, 200), (255, 0, 0, 255)) # A red square
# Or, if you have an actual image file:
# input_image = Image.open('path/to/your/image.png')
# Remove the background
output_image = remove(input_image, session=session)
# Save the result
# output_image.save('output.png')
print("Background removed successfully (output not saved in this example).")
print(f"Original image mode: {input_image.mode}, size: {input_image.size}")
print(f"Output image mode: {output_image.mode}, size: {output_image.size}")
except Exception as e:
print(f"An error occurred: {e}")
print("Please ensure you have an actual image file or mock image data for processing.")
rembg --version
Debug
Known issues
gotchaFirst-time usage requires downloading AI models (100-300 MB each). This causes an initial delay and requires an active internet connection. Models are cached locally in `~/.u2net` for subsequent offline use.fixEnsure an internet connection for the first run. Be aware of the initial delay for model download.
affects: All versions
gotchaFor optimal performance when processing multiple images, explicitly create and reuse a session using `new_session()` instead of relying on the default behavior, which initializes a new session for each call.fixInitialize a session once with `session = new_session()` and pass it to subsequent `remove()` calls: `remove(image, session=session)`.
affects: All versions
gotchaGPU (NVIDIA/CUDA or AMD/ROCm) acceleration (`rembg[gpu]` or `rembg[rocm]`) requires specific system setups including `onnxruntime-gpu` or `onnxruntime-rocm`, potentially CUDA/cudnn-devel or ROCm libraries. Incorrect setup often leads to `ModuleNotFoundError` for `onnxruntime` or `DLL load failed` errors on Windows.fixVerify `onnxruntime` compatibility at `onnxruntime.ai`. On Windows, install the latest Visual C++ Redistributable. For NVIDIA, ensure CUDA and cudnn-devel are correctly installed. If issues persist, revert to `rembg[cpu]`.
affects: All versions with GPU extras
breakingPython version compatibility has changed. Current `rembg` versions require Python `>=3.11, <3.14`. Older versions might have supported broader ranges (e.g., `>=3.7, <3.11`). Using an unsupported Python version will lead to installation failures or `ModuleNotFoundError`.fixUse Python 3.11 or 3.12. Check the PyPI page for the exact `requires_python` range for your target `rembg` version.
affects: Before 2.0.68, and any version outside of `>=3.11, <3.14`
gotchaDepending on the model and image size, `rembg` can be memory-intensive, especially with GPU acceleration. Large images or batch processing can lead to Out Of Memory (OOM) errors.fixConsider processing images in smaller batches, resizing large images before processing, or using a less memory-intensive model (e.g., `u2netp`). Monitor system memory during operation.
affects: All versions
Upgrade
Version history
2.0.81latest on PyPI · released Aug 18, 2026
Audit
Dependencies
onnxruntimeoptionalCore inference engine for CPU. Included with `[cpu]` extra.
onnxruntime-gpuoptionalCore inference engine for NVIDIA/CUDA GPUs. Included with `[gpu]` extra. Requires CUDA and cudnn-devel setup.
onnxruntime-rocmoptionalCore inference engine for AMD/ROCm GPUs. Included with `[rocm]` extra. Requires ROCm setup.
pillowrequiredImage manipulation library, commonly used for input/output.
numpyrequiredNumerical computing library, essential for image data handling.
scipyrequiredScientific computing library, used for various image processing tasks.
pymattingrequiredUsed for alpha matting post-processing.
scikit-imagerequiredCollection of algorithms for image processing.