---
id: willow
version: "1.12.0"
license: unclear
license_treatment: permissive
maintenance: active
---

# Willow — A Python image library that sits on top of Pillow, Wand and OpenCV

License: permissive · Maintenance: active · Downloads: 966.0K/mo

## What it is and what it does

Willow is a wrapper library that unifies the APIs of Pillow, Wand, and OpenCV into a single interface, letting you work with images without needing to know which backend is available. It automatically converts images between libraries when an operation requires a specific backend—for example, face detection uses OpenCV even if you loaded the image with Pillow. The library supports basic image operations (resize, crop, rotate, format conversion) and more specialized tasks like face and feature detection.

It's written in pure Python and supports modern Python versions (3.10–3.14). You install it with low friction—only two small runtime dependencies—and then choose which image backends to install separately based on your needs. This makes it useful in environments where you want flexibility about which image library to use, or where you need to combine capabilities from multiple libraries in a single codebase.

Use it for:

- Build a thumbnail generation service that works with Pillow when available but falls back to Wand on systems where Pillow isn't installed.
- Detect faces in user-uploaded photos by automatically routing to OpenCV when needed, without forcing users to learn OpenCV's API.
- Convert between image formats (PNG, JPEG, WebP, AVIF, HEIC) using a consistent API regardless of which backend is installed.
- Process animated GIFs with frame counting and manipulation across different backends.
- Rotate and crop images with a single codebase that works across Pillow, Wand, and OpenCV without conditional imports.

## Worth the install?

AI-flagged interpretation of the facts above — verify before relying.

Willow provides a unified API for image manipulation across Pillow, Wand, and OpenCV, automatically converting between libraries as needed for operations like resizing, cropping, face detection, and format conversion.

Yes, if you need a unified image API and want to avoid backend lock-in. Install friction is minimal, maintenance is active, and there are no known vulnerabilities. The permissive license poses no restriction. Only caveat: you must separately install at least one of Pillow, Wand, or OpenCV—Willow is a wrapper, not a standalone image library.

## Install

pip install willow
uv add willow
poetry add willow

## Installing Willow

Before you install: Low friction: pure Python wheel with only two runtime dependencies (filetype and defusedxml). Actively maintained with recent commits and a stable release history since 2014.

License in practice: Permissive BSD license allows commercial and private use with minimal restrictions, making it suitable for most projects without legal friction.

Quickstart:

from willow.image import Image

with open('test.png', 'rb') as f:
    img = Image.open(f)
    img = img.resize((100, 100))
    with open('output.png', 'wb') as out:
        img.save_as_png(out)

Requires Python 3.10 or later; at least one of Pillow, Wand, or OpenCV must be installed for actual image processing (not bundled).

Verify before relying:

- Whether Pillow, Wand, or OpenCV are optional or required dependencies (fact sheet lists only filetype and defusedxml as runtime deps).
- Performance characteristics when converting between different backend libraries.
- Whether all listed operations work reliably across all supported Python versions (3.10–3.14).

## Package facts

- License: not declared (permissive)
- Python support: supports_current
- Install friction: low
- Maintenance: active
- Downloads: 966.0K/month (top 5,000 on PyPI)
- Known vulnerabilities: none known

## Tags

image manipulation unified api, pillow wand opencv wrapper, face detection image library, image resize crop convert, multi-backend image processing, animated gif support, image format conversion, image-processing, multi-backend, face-detection

[View on SkillFed](https://skillfed.io/packages/willow) · [View on PyPI](https://pypi.org/project/willow/)