Appendices
Resampling Filters
Pillow provides several resampling filters for use when resizing or transforming images. The filter determines how new pixel values are computed from adjacent pixels. Passed as resample parameter in resize(), thumbnail() and transform().
| Filter | Enum | Quality | Speed | Use Case |
|---|---|---|---|---|
| Nearest Neighbour | Image.Resampling.NEAREST | Low | ⚡⚡⚡⚡⚡ | Pixel art, binary masks — no interpolation. |
| Box | Image.Resampling.BOX | Low+ | ⚡⚡⚡⚡ | Downscaling — average of box neighbourhood. |
| Bilinear | Image.Resampling.BILINEAR | Medium | ⚡⚡⚡ | Good average quality. Faster than Bicubic. |
| Hamming | Image.Resampling.HAMMING | Medium+ | ⚡⚡⚡ | Reduced aliasing vs Bilinear. |
| Bicubic | Image.Resampling.BICUBIC | High | ⚡⚡ | Good quality for upscaling. Default for thumbnail(). |
| Lanczos | Image.Resampling.LANCZOS | Highest | ⚡ | Best quality. Use for print-quality downscaling. |
Resampling Usage
# Highest quality downscale for print
out = img.resize((800, 600), resample=Image.Resampling.LANCZOS)
# Fastest for pixel art or masks
out = img.resize((32, 32), resample=Image.Resampling.NEAREST)
# Good all-rounder for thumbnails
out = img.resize((200, 200), resample=Image.Resampling.BICUBIC)
Transpose Operations
The transpose() method supports image flipping and rotation in 90° increments. Use Image.Transpose.* constants.
| Constant | Effect |
|---|---|
Image.Transpose.FLIP_LEFT_RIGHT | Mirror image horizontally (left-right flip) |
Image.Transpose.FLIP_TOP_BOTTOM | Flip image vertically (upside-down) |
Image.Transpose.ROTATE_90 | Rotate 90° counter-clockwise |
Image.Transpose.ROTATE_180 | Rotate 180° |
Image.Transpose.ROTATE_270 | Rotate 270° counter-clockwise (= 90° clockwise) |
Image.Transpose.TRANSPOSE | Transpose matrix (flip over top-left to bottom-right diagonal) |
Image.Transpose.TRANSVERSE | Transverse (flip over top-right to bottom-left diagonal) |
All Image Methods (Quick Reference)
| Method | Description |
|---|---|
Image.open(fp) | Open and identify the given image file. |
Image.new(mode, size, color) | Create a new image with the given mode and size. |
Image.fromarray(arr) | Create an image from a numpy array. |
Image.frombytes(mode, size, data) | Create a memory-mapped image from raw pixel data bytes. |
im.save(fp, format, **params) | Save the image to a file or stream. |
im.show(title) | Display image using the default viewer. |
im.convert(mode) | Convert image to a different mode. |
im.copy() | Copies this image. Modifications on the copy do not affect the original. |
im.crop(box) | Return a rectangular region. |
im.paste(im2, box, mask) | Paste another image at the given box offset. Optional mask. |
im.resize(size, resample) | Return a resized copy. |
im.rotate(angle, expand) | Return a rotated copy. |
im.thumbnail(size, resample) | Make this image into a thumbnail. In-place. Never upscales. |
im.transpose(method) | Transpose or flip the image. |
im.filter(filter) | Apply an image filter and return a filtered copy. |
im.point(lut) | Map pixel values using a lookup table or function. |
im.transform(size, method, data) | Affine, perspective, mesh, or quad transform. |
im.split() | Split image into individual bands. |
Image.merge(mode, bands) | Merge a set of single band images into a multiband image. |
im.load() | Allocate storage and return a memory-mapped pixel access object. |
im.getpixel(xy) | Return pixel value at given position. |
im.putpixel(xy, value) | Set pixel value at given position. Slow for bulk operations — use load(). |
im.getbands() | Return a tuple of band names. |
im.getbbox() | Calculate the bounding box of the non-zero regions. |
im.getcolors(maxcolors) | Return a list of colours used in an image. |
im.getexif() | Return an Exif object from the image. |
im.histogram() | Return histogram of this image as a list. |
im.quantize(colors) | Convert image to P mode by quantizing to n colors. |
im.reduce(factor) | Returns a copy of the image reduced by factor. |
im.alpha_composite(im2, dest, source) | Alpha composite image im2 over image im in place. |
Image.alpha_composite(im1, im2) | Static: create new composited image. |
Image.blend(im1, im2, alpha) | Create new image by blending two at given alpha. |
Image.composite(image1, image2, mask) | Use mask to composite two images. |
im.seek(frame) | Seek to given frame in sequence. |
im.tell() | Return current frame number. |
im.tobytes(encoder_name) | Return image as bytes object. |
im.tobitmap(name) | Return X11 bitmap data (mode 1 only). |
im.frombytes(data, decoder_name) | Load data into image from bytes object. |
im.verify() | Check file integrity (file pointer reset after call). |
im.close() | Close file pointer and free resources. |
EXIF Auto-Orientation
Many mobile cameras store photos in landscape orientation with an EXIF tag specifying the correct rotation. Without correcting for this, your image may appear rotated. Use ImageOps.exif_transpose() to rotate the image based on its EXIF tag.
Fix EXIF Rotation
from PIL import Image, ImageOps
img = Image.open("camera_photo.jpg")
# Rotate based on EXIF orientation tag
img_corrected = ImageOps.exif_transpose(img)
img_corrected.save("corrected.jpg")
Global Configuration Flags
| Flag | Default | Description |
|---|---|---|
ImageFile.LOAD_TRUNCATED_IMAGES | False | If True, will load truncated/corrupted images instead of raising an error. |
Image.MAX_IMAGE_PIXELS | 178956970 | Maximum pixel count. Prevents decompression bomb attacks. Set to None to disable. |
ImageFont.LAYOUT_BASIC | — | Use basic layout engine (faster but less capable). |
ImageFont.LAYOUT_RAQM | — | Use Raqm library for complex scripts (Arabic, Hebrew, Indic). |
Configuration Examples
from PIL import Image, ImageFile
# Allow loading damaged / truncated files
ImageFile.LOAD_TRUNCATED_IMAGES = True
# Raise the pixel limit to handle very large images
Image.MAX_IMAGE_PIXELS = 300_000_000
# Disable the pixel limit entirely (use with caution)
Image.MAX_IMAGE_PIXELS = None
Security & Limits
Pillow includes a decompression bomb check that prevents loading extremely large images that could trigger excessive memory allocation (a form of DOS attack). If you are processing user-uploaded files, keep this protection enabled.
⚠️ Security Warning: Never disable
MAX_IMAGE_PIXELS when processing untrusted user-uploaded images. A malicious actor could upload a specially crafted file that triggers a decompression bomb — allocating gigabytes of RAM.
| Scenario | Recommendation |
|---|---|
| User photo uploads | Keep default MAX_IMAGE_PIXELS. Use try/except around Image.open(). |
| Satellite / medical imagery | Raise limit to expected size. Document the change. |
| Internal batch processing | Raise or disable only on trusted input paths. |