{"id":2360,"library":"willow","title":"Willow Image Library","description":"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.","status":"active","version":"1.12.0","language":"en","source_language":"en","source_url":"https://github.com/wagtail/Willow","tags":["image processing","Pillow","Wand","OpenCV","graphics","image manipulation","backend"],"install":[{"cmd":"pip install willow","lang":"bash","label":"Core library (no backend)"},{"cmd":"pip install 'willow[Pillow]'","lang":"bash","label":"With Pillow backend (recommended)"},{"cmd":"pip install 'willow[Wand]'","lang":"bash","label":"With Wand (ImageMagick) backend"},{"cmd":"pip install 'willow[OpenCV]'","lang":"bash","label":"With OpenCV backend"}],"dependencies":[{"reason":"Most common image processing backend.","package":"Pillow","optional":true},{"reason":"ImageMagick wrapper backend.","package":"Wand","optional":true},{"reason":"OpenCV backend.","package":"opencv-python","optional":true},{"reason":"Required for HEIC/HEIF support with the Pillow backend.","package":"pillow_heif","optional":true}],"imports":[{"note":"The primary interface for loading and manipulating images, which delegates to an appropriate backend.","symbol":"Image","correct":"from willow.image import Image"},{"note":"Utility to explicitly get the currently active image backend.","symbol":"get_image_backend","correct":"from willow.image import get_image_backend"},{"note":"Direct import for the Pillow-specific image class, useful when you want to force a specific backend.","symbol":"PillowImage","correct":"from willow.plugins.pillow import PillowImage"}],"quickstart":{"code":"import os\nfrom willow.image import Image\n\n# Create dummy image data for demonstration\n# In a real application, you'd load from a file or network stream\ndummy_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\n\ntry:\n    # Load the image using Willow's automatic backend detection\n    # Requires a backend like Pillow to be installed (e.g., pip install 'willow[Pillow]')\n    image = Image.check(dummy_image_data)\n\n    # Get original image properties\n    print(f\"Original format: {image.format}\")\n    print(f\"Original size: {image.get_size()}\")\n\n    # Resize the image\n    image.resize((50, 50))\n\n    # Get new image properties\n    print(f\"Resized size: {image.get_size()}\")\n\n    # Save the processed image data (e.g., as JPEG)\n    processed_data = image.save_as_jpeg()\n\n    # Optionally, save to a file\n    output_filename = 'processed_image.jpg'\n    with open(output_filename, 'wb') as f:\n        f.write(processed_data)\n    print(f\"Image saved to {output_filename}\")\n\n    # Clean up dummy file\n    os.remove(output_filename)\n\nexcept Exception as e:\n    print(f\"Error processing image: {e}\")\n    print(\"Please ensure a backend like Pillow is installed (e.g., pip install 'willow[Pillow]').\")\n","lang":"python","description":"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."},"warnings":[{"fix":"Upgrade Python to 3.10 or a later supported version. For example, `python3.10 -m pip install willow`.","message":"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.","severity":"breaking","affected_versions":">=1.12.0"},{"fix":"Ensure Pillow is updated to version 11.3.0 or higher. For example, `pip install --upgrade 'willow[Pillow]'`.","message":"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.","severity":"breaking","affected_versions":">=1.11.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.","message":"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.","severity":"gotcha","affected_versions":">=1.8.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Install `pillow_heif` in addition to Willow: `pip install 'willow[Pillow]' pillow_heif`.","message":"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.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-09T00:00:00.000Z","next_check":"2026-07-08T00:00:00.000Z"}