Pillow (PIL) Cheat Sheet

Pillow cheat sheet

Pillow (the maintained PIL fork) is the standard library for opening, converting, editing and saving images in Python — the layer under most ML data pipelines (a 🌐 datasets Image, a torchvision input, a matplotlib figure). Core object is Image; helpers live in ImageDraw, ImageFilter, ImageOps, ImageEnhance. This sheet targets Pillow 12.x.

open / inspect / save transform (resize/crop/rotate) compose & draw enhance & filter NumPy & frames gotcha ★ most common

Verified 2026-08-24 against the official docs at pillow.readthedocs.io (Pillow 12.x). Import as from PIL import Image. Interops with NumPy via np.array() / Image.fromarray().

Outline

Open → edit → save. Two things to internalize: most methods return a new image (Pillow is mostly immutable-style), and thumbnail() is the exception that edits in place.

1Open, inspect, saveI/O

pip install Pillow from PIL import Image★
Import name is PIL, package is Pillow.
img = Image.open("photo.jpg")★
Lazy: reads the header only. Pixels load on first use (or call img.load()). Use a with block or it holds the file handle.
img.size · img.width · img.height · img.mode · img.format★
size = (w, h); mode = "RGB"/"L"/"RGBA"/...; format = "JPEG"/"PNG" (None once edited).
img.save("out.png") · img.save("out.jpg", quality=85, optimize=True)★
Format inferred from the extension (or pass format=). quality/optimize for JPEG; img.show() to preview.

2Modes & convertcolor spaces

img.convert("RGB") · img.convert("L") # grayscale★
Modes: "1" (bitmap), "L" (8-bit gray), "RGB", "RGBA" (alpha), "CMYK", "P" (palette).
rgb = img.convert("RGB") # before saving a PNG/RGBA as JPEG★
JPEG can't hold alpha or palette — convert to RGB first or save errors.
img.getbands() · r, g, b = img.split() · Image.merge("RGB", (r,g,b))
Access/recombine channels.

8NumPy & pixelsarrays

import numpy as np arr = np.array(img) # (H, W, C) uint8, RGB★
Pillow → NumPy. Note it's HWC RGB (torchvision wants CHW; cv2 uses BGR).
img = Image.fromarray(arr) # NumPy -> Pillow★
Array must be uint8 (or match a mode). Scale floats to 0–255 first.
img.getpixel((x, y)) · img.putpixel((x, y), (255,0,0))
Single-pixel access (slow in a loop — use NumPy for bulk edits).
img.getdata() · img.histogram()
Flat pixel iterator and per-channel histogram.

9GIFs & multi-frameanimation

gif.n_frames · gif.seek(i) · gif.tell()★
Navigate frames of a GIF/APNG/TIFF. seek moves to frame i.
from PIL import ImageSequence frames = [f.copy() for f in ImageSequence.Iterator(gif)]
Iterate frames cleanly (.copy() because the iterator reuses the object).
frames[0].save("out.gif", save_all=True, append_images=frames[1:], duration=100, loop=0)★
Write an animated GIF: save_all + append_images; duration ms/frame, loop=0 = forever.

!Common gotchasread before shipping

most methods return a NEW image
img.resize(...)/crop/rotate/filter don't mutate — assign the result. thumbnail, paste, and ImageDraw are the in-place exceptions.
JPEG can't save RGBA/P
convert("RGB") before saving a transparent/palette image as JPEG, or it raises.
open() is lazy & holds the file
Use with Image.open(...) as im: im.load() (or work on a copy) so the handle is released — important in servers/loops.
EXIF orientation
Phone photos may display sideways until you call ImageOps.exif_transpose — do it before resizing/cropping.
array layout: HWC RGB
np.array(img) is HWC/RGB. Converting to torch needs CHW; from cv2 needs BGR↔RGB.

Worth memorizing

from PIL import Imagepackage Pillow, import PIL; Image.open is lazy

methods return new imagesassign resize/crop/rotate/filter results; thumbnail & paste mutate

resize vs thumbnailresize = exact size (new img); thumbnail = fit-in-box, in place, keeps aspect

LANCZOS for downscalingImage.Resampling.LANCZOS gives the cleanest shrink

convert("RGB") before JPEGJPEG has no alpha/palette

exif_transpose earlyfix phone-photo orientation before other edits

ImageDraw for boxes/textDraw(img) then rectangle/text; truetype for real fonts

np.array / fromarrayHWC RGB uint8 bridge to NumPy

save_all + append_imageswrite animated GIFs

Pillow cheat sheet

Outline

Basics

Transform

Create

Adjust

Interop

Basics

Transform

Create & Compose

Adjust

Interop

Worth memorizing