pillow-consistency

Pillow — consistent, modern idioms

Pillow 10 removed the constants and metrics APIs that dominate training data — Image.ANTIALIAS, draw.textsize, font.getsize — so generated code crashes on modern installs; and the library's quieter semantics (lazy open, mutating thumbnail vs returning resize, mode/format coupling, EXIF orientation) produce silently wrong images. This skill pins the canonical idiom set for Pillow 10+.

Canonical idioms — always X, never Y

Always	Never	Why
from PIL import Image, ImageDraw, ImageFont	import PIL alone or legacy import Image	Submodules are the API; PIL.Image isn't imported by import PIL.
with Image.open(path) as im: im.load() (or finish work inside the block)	passing lazily-opened images around	open is lazy and holds the file handle; leaks and "seek of closed file" errors follow.
Image.Resampling.LANCZOS (.BICUBIC, .NEAREST)	Image.ANTIALIAS, Image.BICUBIC constants	The bare constants were removed in 10.0; ANTIALIAS crashes every old snippet.
im = im.resize(size) — rebind, it returns new	expecting resize to mutate (or thumbnail to return)	resize returns a copy; thumbnail mutates in place (and keeps aspect). Mixing them up drops work or distorts.
im.convert("RGB") before JPEG save	saving RGBA/P/LA to JPEG directly	JPEG has no alpha/palette: raises OSError: cannot write mode RGBA as JPEG.
ImageOps.exif_transpose(im) right after opening photos	ignoring EXIF orientation	Phone photos carry rotation in metadata; processing strips it → sideways output.
draw.textbbox((x, y), text, font=font) / font.getbbox / draw.textlength	draw.textsize, font.getsize	Removed in 10.0; bbox APIs are the only metrics now.
ImageFont.truetype("DejaVuSans.ttf", 24) with an explicit size	ImageFont.load_default() for visible text	The default bitmap font ignores sizing needs (only newer Pillow can size it).
box/coords as (left, upper, right, lower), origin top-left	width/height or center-based assumptions	Crops and pastes misplace by half an image when the convention is wrong.
ImageOps.fit(im, (w, h)) for exact-size thumbnails	resize-that-distorts or pad-guessing	fit center-crops to the aspect then resizes — the "cover" behavior people want.

House style — safe thumbnails:

from PIL import Image, ImageOps

def make_thumbnail(src: str, dst: str, size: tuple[int, int] = (400, 400)) -> None:
    with Image.open(src) as im:
        im = ImageOps.exif_transpose(im)          # honor camera rotation
        im.thumbnail(size, Image.Resampling.LANCZOS)  # in-place, keeps aspect
        if im.mode != "RGB":                      # JPEG can't take RGBA/P
            im = im.convert("RGB")
        im.save(dst, "JPEG", quality=85, optimize=True)

Pitfalls that produce silently wrong images

• Mode semantics: "RGB" 3×8-bit, "RGBA" +alpha, "L" grayscale, "P" palette, "1" bilevel, "I;16"/"F" high-depth. Operations behave per-mode: pasting RGBA onto RGB without passing the alpha as mask flattens transparency to black boxes — base.paste(overlay, (x, y), overlay) (third arg = mask) or Image.alpha_composite(base_rgba, overlay).
• convert("P")/GIF saves quantize to 256 colors — gradients band; that's the format, not a bug; pick PNG when it matters.
• convert("1") dithers by default; pass dither=Image.Dither.NONE for masks.
• numpy round-trips: np.asarray(im) gives (height, width[, channels]) uint8; Image.fromarray(arr) infers mode from shape/dtype — float arrays must be scaled to 0–255 uint8 first or output is garbage/black.
• im.format is only set by open (None on new/processed images) — save infers from the filename extension; a wrong extension silently writes that wrong format.
• Quality re-encoding: every JPEG save re-compresses; do all edits in one pass from the original, save once (quality 85 is the conventional sweet spot; >95 wastes bytes).
• getpixel/putpixel loops are orders of magnitude too slow — use point(), channel ops (split/merge), ImageEnhance, or numpy for bulk pixel math.
• Text rendering: emoji/CJK need a font that contains them; missing glyphs render as boxes with no error. Multiline metrics need draw.multiline_textbbox.
• Large-image bomb guard: Image.MAX_IMAGE_PIXELS raises DecompressionBombError on huge inputs — handle or consciously raise the limit for trusted sources.

Version notes

Target Pillow 10+ (11 keeps the idioms). The 10.0 removals that break old snippets: Image.ANTIALIAS/LINEAR/CUBIC constants → Image.Resampling.*; draw.textsize/font.getsize/getoffset → textbbox/getbbox/textlength; Image.LANCZOS et al. survive as aliases of the enum members, but write the enum. "PIL" survives only as the import name — the installed package is pillow; the original PIL died in 2011.

Workflow

1. Open in a context manager; immediately exif_transpose photos and note im.mode/im.size.
2. Convert mode deliberately at the start (working mode) and before save (format-legal mode); keep the mode→format compatibility in mind (JPEG:RGB/L, PNG:any, GIF:P).
3. Geometry through the (left, upper, right, lower) convention; thumbnail/fit for aspect-preserving sizing, resize for exact, Resampling.LANCZOS for photo downscales.
4. Composite with alpha masks or alpha_composite; draw text with truetype fonts and bbox metrics.
5. When reviewing, hunt: removed constants/metrics calls, RGBA→JPEG saves, missing exif_transpose, unrebound resize, pixel loops, format-by-wrong-extension.

For the mode/format matrices, removed-API migration table, drawing/text recipes, and numpy interop rules, read references/pillow-patterns.md.