pillow

Pillow Best Practices

Pillow is the definitive image processing library for Python. Adhere to these guidelines to ensure your image manipulation code is robust, performant, and maintainable.

Critical Guidelines:

1. Resource Management: Always Use Context Managers

Images opened from files consume system resources. Ensure they are properly closed using with statements.

❌ BAD:

from PIL import Image

im = Image.open("input.jpg")
# ... process im ...
# Resource might leak if not explicitly closed or on error
# im.close() # Often forgotten, especially on exceptions

✅ GOOD:

from PIL import Image

def process_image_with_thumbnail(path: str) -> None:
    with Image.open(path) as im:
        # Image is automatically closed when exiting the 'with' block
        im.thumbnail((128, 128))
        im.save("thumbnail.jpg")

2. Prefer High-Level API for Common Operations

Pillow provides a rich, high-level API for most common image transformations. Use these methods instead of manual pixel manipulation or low-level ImageFile operations.

❌ BAD:

from PIL import Image
# Avoid manual pixel access for transformations; it's inefficient and error-prone
def resize_manual(im: Image.Image, size: tuple[int, int]) -> Image.Image:
    new_im = Image.new(im.mode, size)
    # ... complex, slow loop to copy pixels ...
    return new_im

✅ GOOD:

from PIL import Image, ImageFilter

def apply_common_transforms(im: Image.Image) -> Image.Image:
    # Use built-in methods for efficiency and correctness
    im_resized = im.resize((256, 256), Image.Resampling.LANCZOS)
    im_rotated = im_resized.rotate(45, expand=True)
    im_blurred = im_rotated.filter(ImageFilter.BLUR)
    return im_blurred

3. Explicitly Import Custom Plugins

Pillow no longer auto-loads plugins (since 2.1.0). If you're using a custom image format or a third-party plugin, you must import it explicitly before use.

❌ BAD:

from PIL import Image
# Assuming 'MyCustomImagePlugin.py' is on PYTHONPATH
# This will fail if MyCustomImagePlugin is not explicitly imported
try:
    with Image.open("custom.myformat") as im:
        im.save("output.png")
except Exception as e:
    print(f"Error: {e}") # Likely 'cannot identify image file'