Willow image library

A wrapper that combines the functionality of multiple Python image libraries into one API.

Overview

Willow is a simple image library that combines the APIs of Pillow, Wand and OpenCV. It converts the image between the libraries when necessary.

Willow currently has basic resize and crop operations, face and feature detection and animated GIF support. New operations and library integrations can also be easily implemented.

The library is written in pure Python and supports versions 3.10, 3.11, 3.12, 3.13 and 3.14.

Examples

Resizing an image

from willow.image import Image

f = open('test.png', 'rb')
img = Image.open(f)

# Resize the image to 100x100 pixels
img = img.resize((100, 100))

# Save it
with open('test_thumbnail.png', 'wb') as out:
   img.save_as_png(out)

This will open the image file with Pillow or Wand (if Pillow is unavailable).

It will then resize it to 100x100 pixels and save it back out as a PNG file.

Detecting faces

from willow.image import Image

f = open('photo.png', 'rb')
img = Image.open(f)

# Find faces
faces = img.detect_faces()

Like above, the image file will be loaded with either Pillow or Wand.

As neither Pillow nor Wand support detecting faces, Willow would automatically convert the image to OpenCV and use that to perform the detection.

Available operations

Documentation

Operation	Pillow	Wand	OpenCV
`get_size()`	✓	✓	✓
`get_frame_count()`	✓**	✓	✓**
`resize(size)`	✓	✓
`crop(rect)`	✓	✓
`rotate(angle)`	✓	✓
`set_background_color_rgb(color)`	✓	✓
`transform_colorspace_to_srgb(rendering_intent)`	✓
`auto_orient()`	✓	✓
`save_as_jpeg(file, quality)`	✓	✓
`save_as_png(file)`	✓	✓
`save_as_gif(file)`	✓	✓
`save_as_webp(file, quality)`	✓	✓
`save_as_heic(file, quality, lossless)`	✓⁺
`save_as_avif(file, quality, lossless)`	✓	✓
`save_as_ico(file)`	✓	✓
`has_alpha()`	✓	✓	✓*
`has_animation()`	✓*	✓	✓*
`get_pillow_image()`	✓
`get_wand_image()`		✓
`detect_features()`			✓
`detect_faces(cascade_filename)`			✓

* Always returns False

** Always returns 1

⁺ Requires the pillow-heif library

Release files for Willow 1.12.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for Willow 1.12.0
File	Size	Uploaded
willow-1.12.0.tar.gz	113.7 kB	Oct 26, 2025	Details

Built distribution (wheel)

Table of built distributions (wheels) for Willow 1.12.0
File	Interpreter	ABI	Platform	Reset
willow-1.12.0-py3-none-any.whl 119.4 kB Oct 26, 2025	Python 3	none	any	Details

Total release size: 233.2 kB

Release files / willow-1.12.0.tar.gz

Download URL	willow-1.12.0.tar.gz
Size	113.7 kB
Tags	Source
SHA-256 checksum How to use checksums	`db29c8d2f19b9d91f4ce22881521055aa2f6070131d64b4098cb86a98e851a70`
BLAKE2b-256 checksum How to use checksums	`215693e0bc60a3f9fe3b8ad9bac96c34179d1f4f37d42c8fddcf8de16ba5a711`
Upload date	Oct 26, 2025
Uploaded using Trusted Publishing? What is trusted publishing?	Yes
Uploaded via	`twine/6.1.0 CPython/3.13.7`

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Identity

Publishing platform: GitHub Actions
Publishing repository: github.com/wagtail/Willow
Publishing commit: github.com/wagtail/Willow/tree/e98b89fafd31b5c217fe703d3afab42b7c6e382e

Workflow

Publishing configuration: github.com/wagtail/Willow/blob/e98b89fafd31b5c217fe703d3afab42b7c6e382e/.github/workflows/publish.yml
Publishing logs: github.com/wagtail/Willow/actions/runs/18818553172/attempts/1

Artifact

Subject: willow-1.12.0.tar.gz
SHA-256 checksum: db29c8d2f19b9d91f4ce22881521055aa2f6070131d64b4098cb86a98e851a70 Verifying attestations

Release files / willow-1.12.0-py3-none-any.whl

Download URL	willow-1.12.0-py3-none-any.whl
Size	119.4 kB
Tags	Python 3
SHA-256 checksum How to use checksums	`d3541690b6726a4f6f4654f80507d81bacfa0c686ab065eb5c90159f1b9cee38`
BLAKE2b-256 checksum How to use checksums	`76efa2e237f856b374e466fba458a6188a73fd68db7fb6b76706ce454980092f`
Upload date	Oct 26, 2025
Uploaded using Trusted Publishing? What is trusted publishing?	Yes
Uploaded via	`twine/6.1.0 CPython/3.13.7`

Provenance

Identity

Publishing platform: GitHub Actions
Publishing repository: github.com/wagtail/Willow
Publishing commit: github.com/wagtail/Willow/tree/e98b89fafd31b5c217fe703d3afab42b7c6e382e

Workflow

Publishing configuration: github.com/wagtail/Willow/blob/e98b89fafd31b5c217fe703d3afab42b7c6e382e/.github/workflows/publish.yml
Publishing logs: github.com/wagtail/Willow/actions/runs/18818553172/attempts/1

Artifact

Subject: willow-1.12.0-py3-none-any.whl
SHA-256 checksum: d3541690b6726a4f6f4654f80507d81bacfa0c686ab065eb5c90159f1b9cee38 Verifying attestations