Willow Image Library

1.12.0 · active · verified Thu Apr 09

Willow is a Python image library that provides a unified API over multiple backend imaging libraries such as Pillow, Wand (ImageMagick), and OpenCV. It offers common image manipulation capabilities like resizing, cropping, and format conversion, allowing developers to switch backends with minimal code changes. The current version is 1.12.0, and it maintains a regular release cadence, often aligning with new Python and backend library versions.

Warnings

breaking Willow v1.12.0 and later have dropped support for Python 3.9. Users on Python 3.9 must upgrade their Python environment to 3.10 or newer to use the latest Willow versions.
Fix: Upgrade Python to 3.10 or a later supported version. For example, `python3.10 -m pip install willow`.
breaking Willow v1.11.0 raised the minimum required Pillow version to 11.3.0. Further, v1.12.0 added support for Pillow 12+. Using older Pillow versions (below 11.3.0) with recent Willow releases will lead to compatibility issues, especially with newer image formats like AVIF.
Fix: Ensure Pillow is updated to version 11.3.0 or higher. For example, `pip install --upgrade 'willow[Pillow]'`.
gotcha Starting with Willow v1.8.0, CMYK images with an ICC profile are automatically converted to sRGB before encoding (e.g., to PNG, WebP, AVIF, HEIC). This is done to ensure accurate color representation, as Pillow's default CMYK to RGB conversion historically ignored profiles. This change might result in slightly different color appearances for such images compared to versions prior to v1.8.0.
Fix: Be aware of this automatic color space conversion when processing CMYK images. If you require custom CMYK handling, you may need to preprocess images before passing them to Willow.
gotcha A plain `pip install willow` only installs the core library without any backend. To get functional image processing capabilities, you must install Willow with at least one optional backend dependency, such as Pillow, Wand, or OpenCV.
Fix: Install Willow with the desired backend using the bracket syntax, e.g., `pip install 'willow[Pillow]'` for the Pillow backend, which is generally recommended for most use cases.
gotcha For HEIC/HEIF image format support when using the Pillow backend, the `pillow_heif` library is required. This library is not included with `willow[Pillow]` by default and must be installed separately.
Fix: Install `pillow_heif` in addition to Willow: `pip install 'willow[Pillow]' pillow_heif`.

Install

pip install willow Core library (no backend)
pip install 'willow[Pillow]' With Pillow backend (recommended)
pip install 'willow[Wand]' With Wand (ImageMagick) backend
pip install 'willow[OpenCV]' With OpenCV backend

Imports

Image
```
from willow.image import Image
```
The primary interface for loading and manipulating images, which delegates to an appropriate backend.
get_image_backend
```
from willow.image import get_image_backend
```
Utility to explicitly get the currently active image backend.
PillowImage
```
from willow.plugins.pillow import PillowImage
```
Direct import for the Pillow-specific image class, useful when you want to force a specific backend.

Quickstart

This quickstart demonstrates how to load, resize, and save an image using Willow. It automatically detects the best available backend (like Pillow) and performs common image manipulations. Ensure you have installed Willow with at least one backend (e.g., `pip install 'willow[Pillow]'`) for this code to run successfully.

import os
from willow.image import Image

# Create dummy image data for demonstration
# In a real application, you'd load from a file or network stream
dummy_image_data = b'GIF89a\x01\x00\x01\x00\x00\xff\x00,\x00\x00\x00\x00\x01\x00\x01\x00\x00\x02\x00;' # Minimal valid GIF

try:
    # Load the image using Willow's automatic backend detection
    # Requires a backend like Pillow to be installed (e.g., pip install 'willow[Pillow]')
    image = Image.check(dummy_image_data)

    # Get original image properties
    print(f"Original format: {image.format}")
    print(f"Original size: {image.get_size()}")

    # Resize the image
    image.resize((50, 50))

    # Get new image properties
    print(f"Resized size: {image.get_size()}")

    # Save the processed image data (e.g., as JPEG)
    processed_data = image.save_as_jpeg()

    # Optionally, save to a file
    output_filename = 'processed_image.jpg'
    with open(output_filename, 'wb') as f:
        f.write(processed_data)
    print(f"Image saved to {output_filename}")

    # Clean up dummy file
    os.remove(output_filename)

except Exception as e:
    print(f"Error processing image: {e}")
    print("Please ensure a backend like Pillow is installed (e.g., pip install 'willow[Pillow]').")

view raw JSON →