Install & Compatibility
Where this runs
tested against v1.12.0 · 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
muslpy 3.10–3.920 runs
installs and imports cleanly · install 0.0s · import 0.229s · 38.9MB
glibcpy 3.10–3.920 runs
installs and imports cleanly · install 1.9s · import 0.215s · 40MB
37MB installed
● package 37MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
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.
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]').")
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'willow'
The `willow` library has not been installed in the current Python environment.
willow.exceptions.WillowException: No suitable backend found for operation
The `willow` library requires at least one supported backend imaging library (such as Pillow, Wand, or OpenCV) to be installed to perform image operations, and none were found or detected.
fixpip install willow[pillow] # or willow[wand] or willow[opencv] depending on your preferred backend
willow.exceptions.BadImageOperationError: Cannot identify image file
The provided file-like object or path does not contain a recognizable image format, or the image data is corrupted.
fixEnsure the input file is a valid and supported image format (e.g., JPEG, PNG, GIF) and that the file is not corrupted.
AttributeError: 'Image' object has no attribute 'save_as_jpg'
The `willow.image.Image` object does not have a method named `save_as_jpg`; the correct method for saving as JPEG is `save_as_jpeg`.
fiximage.save_as_jpeg(output_file_object)
ImportError: libMagickWand-6.Q16.so: cannot open shared object file: No such file or directory
The `wand` backend, if chosen by `willow`, cannot find the underlying ImageMagick shared library files required for its operation on the system.
fixInstall ImageMagick and its development files on your operating system (e.g., `sudo apt-get install imagemagick libmagickwand-dev` on Debian/Ubuntu, or `brew install imagemagick` on macOS).
Upgrade
Version history
1.12.0latest on PyPI · released Oct 26, 2025
Audit
Dependencies
PillowoptionalMost common image processing backend.
WandoptionalImageMagick wrapper backend.
opencv-pythonoptionalOpenCV backend.
pillow_heifoptionalRequired for HEIC/HEIF support with the Pillow backend.