resizebox-background-remover

AI background removal for Python by ResizeBox.com: https://resizebox.com/remove-background

Built by ResizeBox.com, a privacy-focused image toolkit. Images are processed locally in your Python process.

Install

pip install resizebox-background-remover

Remove a background

from resizebox_background_remover import remove_background

result = remove_background(
    "input.jpg",
    "output.png",
)

print(result.width, result.height)

The first run downloads the quantized onnx-community/ormbg-ONNX model from Hugging Face and caches it locally. The model is then executed locally with ONNX Runtime. Your image is not uploaded to ResizeBox or Hugging Face.

Work with bytes

from resizebox_background_remover import remove_background

with open("input.webp", "rb") as file:
    source = file.read()

result = remove_background(source)

with open("result.png", "wb") as file:
    file.write(result.data)

bytes, bytearray, binary file-like objects, str paths, and pathlib.Path are supported as inputs.

Solid background color

Transparent PNG is the default output. A six-digit hex color can be used instead:

result = remove_background(
    "input.png",
    "white-background.png",
    background="#FFFFFF",
)

Preload the model

Download and initialize the model before processing the first image:

from resizebox_background_remover import preload_model

model_path = preload_model()
print(model_path)

You can provide a custom Hugging Face cache directory:

preload_model(cache_dir="./model-cache")

ONNX Runtime providers

By default, ONNX Runtime chooses the providers available in the current Python environment. You can explicitly select providers when needed:

result = remove_background(
    "input.jpg",
    providers=["CPUExecutionProvider"],
)

Result

Every call returns a BackgroundRemovalResult:

result.data        # PNG bytes
result.width
result.height
result.mime_type   # "image/png"
result.filename
result.output_path

Errors

Validation, model download, model initialization, inference, and encoding failures raise BackgroundRemoverError with a machine-readable code.

from resizebox_background_remover import BackgroundRemoverError, remove_background

try:
    remove_background("input.jpg")
except BackgroundRemoverError as error:
    print(error.code)

Input and output

Supported input formats:

• JPEG
• PNG
• WebP

Output format:

• PNG with transparency by default
• PNG composited onto a custom solid background when requested

The package validates decoded image format, file size, image dimensions, and model output before returning a result.

Model

The model is not bundled into the PyPI package. On first use, the package downloads:

onnx-community/ormbg-ONNX/onnx/model_quantized.onnx

The model repository is licensed separately under Apache-2.0. The Python package code is licensed under MIT.

Privacy

Image processing runs locally in your Python process. Image content is not uploaded to ResizeBox or Hugging Face. Hugging Face is contacted only to download the AI model file.

Website: https://resizebox.com/remove-background

Privacy Policy: https://resizebox.com/privacy-policy

License

MIT