Short answer

Two images are pixel-identical when ImageChops.difference(a, b).getbbox() is None; otherwise that box is where they differ. Check the sizes yourself first: different sizes do not raise, the result silently covers only the overlap. Different modes raise ValueError: images do not match. Convert RGBA to RGB before comparing colours, and use a tolerance for JPEGs, which never match exactly after re-saving.

Are two images identical?

compare_images.py
from PIL import Image, ImageChops

a = Image.open("photo.jpg")
b = a.copy()
b.paste((255, 0, 0), (700, 500, 720, 520))                      # change a 20x20 square

diff = ImageChops.difference(a, b)
print("identical?", diff.getbbox() is None)
print("changed region:", diff.getbbox())

resaved = Image.open("photo.jpg")
resaved.save("again.jpg", quality=92)
diff2 = ImageChops.difference(a, Image.open("again.jpg"))
print("re-saved JPEG identical?", diff2.getbbox() is None, " largest channel difference:", max(hi for lo, hi in diff2.getextrema()))
Output
identical? False
changed region: (700, 500, 720, 520)
re-saved JPEG identical? False  largest channel difference: 27

Compare a.size == b.size before trusting the answer (see the rules below).

getbbox() returns the smallest box containing every non-black pixel, so on a difference image it is None for identical images and otherwise the changed area. A JPEG saved again is not identical even at the same quality: every save re-quantises the pixels. Comparing files byte for byte is stricter still, since metadata or a different encoder changes the bytes without changing a pixel.

How different? A percentage and a tolerance

how_different.py
from PIL import Image, ImageChops, ImageStat

a = Image.open("photo.jpg").convert("RGB")
b = a.copy()
b.paste((255, 0, 0), (700, 500, 720, 520))                      # a 20x20 red square
a.save("again.jpg", quality=70)
c = Image.open("again.jpg").convert("RGB")                       # the same photo, JPEG-compressed again


def compare(x, y, tolerance=16):
    diff = ImageChops.difference(x, y).convert("L")              # per pixel: largest change becomes brightness
    changed = diff.point(lambda v: 255 if v > tolerance else 0)  # ignore small changes (compression noise)
    share = ImageStat.Stat(changed).mean[0] / 255
    rms = ImageStat.Stat(ImageChops.difference(x, y)).rms
    return f"{share:7.3%} of pixels changed   RMS difference {sum(rms) / 3:5.2f}   box {changed.getbbox()}"


print("red square:  ", compare(a, b))
print("re-saved q70:", compare(a, c))
print("re-saved q70, tolerance 0:", compare(a, c, tolerance=0).split("   ")[0].strip())
Output
red square:    0.023% of pixels changed   RMS difference  2.10   box (700, 500, 720, 520)
re-saved q70:  0.235% of pixels changed   RMS difference  2.89   box (454, 294, 1394, 839)
re-saved q70, tolerance 0: 74.255% of pixels changed

Two numbers answer different questions. The share of changed pixels, counted above a tolerance, says how much of the picture changed and ignores compression noise: the red square is 0.023% of the photo, and a JPEG re-saved at quality 70 changes 74% of its pixels by at least one level but only 0.2% by more than 16. The RMS difference says how strongly pixels changed on average, including the noise. For near-duplicate detection across resized or recompressed copies, compare small greyscale thumbnails or use a perceptual hash (the imagehash package), not exact pixels.

Highlight what changed

Three panels: a photo, the same photo with three small edits, and the edited photo with the three changes painted red and outlined in yellow
Real output. Before, after, and the changes found by difference(), tinted and outlined.
highlight_changes.py
from PIL import Image, ImageChops, ImageDraw, ImageFilter

before = Image.open("photo.jpg").convert("RGB").resize((800, 534))
after = before.copy()
d = ImageDraw.Draw(after)
d.ellipse((540, 150, 600, 210), fill=(250, 250, 240))            # three changes to find
d.rectangle((90, 400, 170, 440), fill=(30, 30, 30))
after.paste(after.crop((300, 60, 360, 120)).transpose(Image.Transpose.FLIP_LEFT_RIGHT), (300, 60))

diff = ImageChops.difference(before, after).convert("L")
mask = diff.point(lambda v: 255 if v > 24 else 0).filter(ImageFilter.MaxFilter(9))   # grow the changed pixels a little
red = Image.new("RGB", after.size, (255, 40, 40))
marked = Image.composite(red, after, mask.point(lambda v: v * 0.6))      # paint changes red at 60%
outline = mask.filter(ImageFilter.FIND_EDGES)
marked.paste((255, 255, 0), mask=outline)                                 # and outline them

sheet = Image.new("RGB", (3 * 400 + 20, 267), "white")
for i, im in enumerate([before, after, marked]):
    sheet.paste(im.resize((400, 267)), (i * 410, 0))
sheet.save("highlight.png")
print("changed areas:", mask.getbbox())
Output
changed areas: (86, 56, 605, 445)

The threshold turns the difference into a mask, MaxFilter grows it so single pixels become visible areas, and Image.composite() paints through it. For visual regression tests, save this marked image next to the failing screenshot.

Trim a border or whitespace

trim_border.py
from PIL import Image, ImageChops, ImageOps

photo = Image.open("photo.jpg").convert("RGB").resize((400, 267))
framed = ImageOps.expand(photo, border=(60, 30, 20, 45), fill="white")    # uneven white margins
framed.save("scan.jpg", quality=80)                                       # JPEG adds noise to the "white"
scan = Image.open("scan.jpg")


def trim(img, fuzz=30):
    bg = Image.new(img.mode, img.size, img.getpixel((0, 0)))              # the border colour, from the corner
    diff = ImageChops.difference(img, bg)
    diff = ImageChops.add(diff, diff, 2.0, -fuzz)                         # (d + d) / 2 - fuzz: drop near-white noise
    box = diff.getbbox()
    return img.crop(box) if box else img


print("scan:", scan.size, "-> trimmed:", trim(scan).size, "| photo was", photo.size)
print("without fuzz:", ImageChops.difference(scan, Image.new("RGB", scan.size, scan.getpixel((0, 0)))).getbbox())
Output
scan: (480, 342) -> trimmed: (401, 267) | photo was (400, 267)
without fuzz: (47, 15, 465, 304)

This is the common “auto-crop” recipe: compare the image with a flat image of its corner colour and crop to the bounding box of whatever differs. The add(diff, diff, 2.0, -fuzz) line subtracts fuzz from every difference, which matters on scans and JPEGs: without it the faint noise in the margin counts as content and nothing is trimmed, as the last line shows (the box is the whole image). Raise fuzz for noisier scans, lower it for borders close to the content colour.

Blend modes, side by side

The same photo combined with a black-to-white gradient, so each panel shows what a mode does from a black top layer (left) to a white one (right):

Twelve panels of a photo combined with a horizontal gradient using multiply, screen, overlay, soft light, hard light, darker, lighter, add, subtract, difference, blend and add modulo
Real output of the script below.
blend_modes.py
from PIL import Image, ImageChops

base = Image.open("photo.jpg").convert("RGB").resize((600, 400))
ramp = Image.linear_gradient("L").rotate(90).resize((600, 400)).convert("RGB")   # black on the left, white on the right
ops = [
    ("multiply", ImageChops.multiply), ("screen", ImageChops.screen), ("overlay", ImageChops.overlay),
    ("soft_light", ImageChops.soft_light), ("hard_light", ImageChops.hard_light), ("darker", ImageChops.darker),
    ("lighter", ImageChops.lighter), ("add", ImageChops.add), ("subtract", ImageChops.subtract),
    ("difference", ImageChops.difference), ("blend 0.5", lambda a, b: ImageChops.blend(a, b, 0.5)),
    ("add_modulo", ImageChops.add_modulo),
]
from PIL import ImageDraw, ImageFont
font = ImageFont.load_default(size=22)
sheet = Image.new("RGB", (4 * 310 - 10, 3 * 240), "white")
for i, (name, fn) in enumerate(ops):
    x, y = (i % 4) * 310, (i // 4) * 240
    sheet.paste(fn(base, ramp).resize((300, 200)), (x, y))
    ImageDraw.Draw(sheet).text((x + 150, y + 220), name, font=font, fill="black", anchor="mm")
sheet.save("blend_modes.png")
Result for a base pixel of 100 as the top layer goes from 0 to 255Multiply only darkens, screen only lightens, overlay and soft light pass through the original value at a 128 top layer.
multiplyscreenoverlaysoft light
01002003000326496128160192224 screenoverlaysoft lightmultiplyTop layer valueResult

Recorded by the build from ImageChops on Pillow 13.

Show the numbers
Top layer valuemultiplyscreenoverlaysoft light
00100039
10101039
20102140
31102240
41103340
51104341
62104441
72105542
83105642
93106743
103107743
114107843
124108944
1351081045
1451091145
1551101146
1661101246
1761111347
1871111447
1971121447
2071131548
2181131648
2281141749
2391141849
2491151850
2591161950
26101162051
27101172151
28101182252
29111182252
30111192353
31121192453
32121202554
33121212554
34131212655
35131222755
36141222855
37141232956
38141242956
39151243057
40151253158
41161253258
42161263358
43161273359
44171273459
45171283560
46181283660
47181293761
48181303761
49191303861
50191313962
51201314063
52201324063
53201334164
54211334264
55211344365
56211354465
57221354465
58221364566
59231364666
60231374767
61231384868
62241384868
63241394968
64251395069
65251405169
66251415170
67261415270
68261425371
69271425471
70271435572
71271445572
72281445673
73281455773
74291455873
75291465974
76291475974
77301476075
78301486176
79301496276
80311496276
81311506377
82321506477
83321516578
84321526678
85331526679
86331536780
87341536880
88341546980
89341557081
90351557081
91351567182
92361567282
93361577382
94361587483
95371587483
96371597584
97381597684
98381607785
99381617786
100391617886
101391627986
102401628087
103401638187
104401648188
105411648288
106411658389
107411668490
108421668590
109421678590
110431678691
111431688791
112431698892
113441698892
114441708992
115451709093
116451719194
117451729294
118461729294
119461739395
120471739495
121471749596
122471759696
123481759697
124481769798
125491769898
126491779998
1274917810099
1285017810099
12950179101100
13050180102100
13151180103100
13251181103101
13352181104101
13452182105102
13552183106102
13653183107103
13753184107104
13854184108104
13954185109104
14054186110105
14155186111105
14255187111106
14356187112106
14456188113107
14556189114108
14657189114108
14757190115108
14858190116109
14958191117109
15058192118110
15159192118110
15259193119110
15360193120111
15460194121112
15560195122112
15661195122112
15761196123113
15861197124114
15962197125114
16062198125114
16163198126115
16263199127116
16363200128116
16464200129116
16564201129117
16665201130117
16765202131118
16865203132118
16966203133118
17066204133120
17167204134120
17267205135120
17367206136120
17468206137121
17568207137122
17669207138122
17769208139122
17869209140123
17970209140123
18070210141124
18170211142124
18271211143125
18371212144126
18472212144126
18572213145126
18672214146126
18773214147127
18873215148128
18974215148128
19074216149128
19174217150130
19275217151130
19375218151130
19476218152130
19576219153131
19676220154132
19777220155132
19877221155132
19978221156133
20078222157134
20178223158134
20279223159134
20379224159135
20480224160135
20580225161136
20680226162136
20781226162136
20881227163138
20981228164138
21082228165138
21182229166138
21283229166139
21383230167140
21483231168140
21584231169140
21684232170141
21785232170141
21885233171142
21985234172142
22086234173143
22186235174144
22287235174144
22387236175144
22487237176144
22588237177145
22688238177146
22789238178146
22889239179146
22989240180148
23090240181148
23190241181148
23290242182148
23391242183149
23491243184150
23592243185150
23692244185150
23792245186152
23893245187152
23993246188152
24094246188152
24194247189152
24294248190154
24395248191154
24495249192154
24596249192154
24696250193156
24796251194156
24897251195156
24997252196156
25098252196157
25198253197158
25298254198158
25399254199158
25499255200160
255100255200160
blend_curves.py
import json
from PIL import Image, ImageChops

base = Image.new("L", (256, 1), 100)                     # a mid-dark pixel...
layer = Image.linear_gradient("L").rotate(90).resize((256, 1))   # ...against every top-layer value 0-255
curves = {name: list(getattr(ImageChops, name)(base, layer).get_flattened_data())
          for name in ["multiply", "screen", "overlay", "soft_light"]}
print(json.dumps(curves))

The formulas, verified

Each function computed on one pixel pair (100 and 200) and checked against its formula:

blend_formulas.py
from PIL import Image, ImageChops

A, B = 100, 200                                          # one pixel value in each image


def px(v):
    return Image.new("L", (1, 1), v)


def run(fn, *args):
    return fn(px(A), px(B), *args).getpixel((0, 0))


checks = [
    ("add",             run(ImageChops.add),               min(255, A + B)),
    ("add scale=2",     run(ImageChops.add, 2.0),          (A + B) // 2),
    ("add_modulo",      run(ImageChops.add_modulo),        (A + B) % 256),
    ("subtract",        ImageChops.subtract(px(A), px(B)).getpixel((0, 0)), max(0, A - B)),
    ("subtract_modulo", ImageChops.subtract_modulo(px(A), px(B)).getpixel((0, 0)), (A - B) % 256),
    ("difference",      run(ImageChops.difference),        abs(A - B)),
    ("multiply",        run(ImageChops.multiply),          A * B // 255),
    ("screen",          run(ImageChops.screen),            255 - (255 - A) * (255 - B) // 255),
    ("darker",          run(ImageChops.darker),            min(A, B)),
    ("lighter",         run(ImageChops.lighter),           max(A, B)),
    ("blend 0.25",      run(ImageChops.blend, 0.25),       round(A * 0.75 + B * 0.25)),
]
print(f"{'function':<16}{'Pillow':>7}{'formula':>9}")
for name, got, want in checks:
    print(f"{name:<16}{got:>7}{want:>9}{'' if abs(got - want) <= 1 else '   <- differs'}")
Output
function         Pillow  formula
add                 255      255
add scale=2         150      150
add_modulo           44       44
subtract              0        0
subtract_modulo     156      156
difference          100      100
multiply             78       78
screen              222      222
darker              100      100
lighter             200      200
blend 0.25          125      125

The plain functions clip to 0–255; the _modulo variants wrap around, which is almost never what you want for photos (bright plus bright becomes dark) but is exactly right for counters stored in pixels. add and subtract also take scale and offset: add(a, b, 2.0) is the average of two images, and subtract(a, b, 1, 128) shows a signed difference with grey as zero.

Size and mode rules, and ValueError: images do not match

what_chops_accepts.py
from PIL import Image, ImageChops

photo = Image.open("photo.jpg")
small = photo.resize((800, 533))
print("different sizes, no error:", photo.size, "vs", small.size, "->", ImageChops.difference(photo, small).size)
for a, b, label in [
    (photo.convert("RGB"), photo.convert("L"), "RGB and L"),
    (photo.convert("RGB"), photo.convert("RGBA"), "RGB and RGBA"),
]:
    try:
        ImageChops.difference(a, b)
    except ValueError as e:
        print(f"{label:<16} ValueError: {e}")

print(f"{'mode':<6}{'difference':<14}{'multiply':<14}{'logical_and':<14}{'invert':<9}{'offset'}")
for mode in ["L", "RGB", "RGBA", "CMYK", "P", "1", "I", "I;16", "F"]:
    im = photo.convert("I").convert("I;16") if mode == "I;16" else photo.convert(mode)
    row = []
    for fn in [ImageChops.difference, ImageChops.multiply, ImageChops.logical_and,
               ImageChops.invert, lambda x: ImageChops.offset(x, 10)]:
        try:
            fn(im) if fn in (ImageChops.invert,) or fn.__name__ == "<lambda>" else fn(im, im)
            row.append("ok")
        except ValueError:
            row.append("ValueError")
    print(f"{mode:<6}{row[0]:<14}{row[1]:<14}{row[2]:<14}{row[3]:<9}{row[4]}")
Output
different sizes, no error: (1600, 1067) vs (800, 533) -> (800, 533)
RGB and L        ValueError: images do not match
RGB and RGBA     ValueError: images do not match
mode  difference    multiply      logical_and   invert   offset
L     ok            ok            ValueError    ok       ok
RGB   ok            ok            ValueError    ok       ok
RGBA  ok            ok            ValueError    ok       ok
CMYK  ok            ok            ValueError    ok       ok
P     ok            ok            ValueError    ok       ok
1     ok            ok            ok            ok       ok
I     ValueError    ValueError    ValueError    ok       ok
I;16  ValueError    ValueError    ValueError    ok       ok
F     ValueError    ValueError    ValueError    ok       ok
  • Same mode, always: convert both, usually to RGB.
  • Same size is not checked. The result has the size of the overlap (the smaller width and height, from the top-left corner), so a comparison of a photo with its thumbnail compares the wrong pixels without any error. Check a.size == b.size, or resize one to match.
  • 8-bit modes only for the arithmetic and blend functions. I, I;16 and F raise ValueError: image has wrong mode; use ImageMath or NumPy for those.
  • logical_and, logical_or, logical_xor need mode 1. Convert masks with mask.convert("1"), or threshold first with point().

Two silent traps: RGBA and palette images

chops_gotchas.py
from PIL import Image, ImageChops

a = Image.open("logo.png").convert("RGBA")
b = a.copy()
b.paste((255, 0, 0, 255), (100, 100, 140, 140))
d = ImageChops.difference(a, b)
print("RGBA difference, alpha where nothing changed:", d.getpixel((300, 180))[3], "(0 = invisible)")
rgb = ImageChops.difference(a.convert("RGB"), b.convert("RGB"))
print("compare RGB instead, then check alpha on its own:", rgb.getbbox(),
      ImageChops.difference(a.getchannel("A"), b.getchannel("A")).getbbox())

p1 = Image.open("photo.jpg").quantize(64)
p2 = p1.remap_palette(list(range(63, -1, -1)))          # same colours, palette stored in reverse order
print("P images look the same:", p1.convert("RGB").tobytes() == p2.convert("RGB").tobytes(),
      "| ImageChops sees a difference:", ImageChops.difference(p1, p2).getbbox() is not None)
Output
RGBA difference, alpha where nothing changed: 0 (0 = invisible)
compare RGB instead, then check alpha on its own: (100, 100, 140, 140) (100, 100, 140, 140)
P images look the same: True | ImageChops sees a difference: True

On RGBA images difference() also subtracts the alpha channels, so wherever both images are opaque the result has alpha 0 and displays as fully transparent, which looks like “the difference image is empty”. Compare the colour channels as RGB and the alpha channel on its own. Palette (P) images are accepted without complaint, but the function works on palette indexes, so two images that look the same can “differ” everywhere. Convert them to RGB first.

offset(): wrap an image around

offset_wrap.py
from PIL import Image, ImageChops

tile = Image.open("photo.jpg").convert("RGB").crop((0, 0, 256, 256))
shifted = ImageChops.offset(tile, 128, 128)              # wraps around: the edges now meet in the middle
shifted.save("seam_check.png")
print("pixel (0, 0) moved to (128, 128):", tile.getpixel((0, 0)) == shifted.getpixel((128, 128)))
print("wrap: pixel (200, 200) is now at", ((200 + 128) % 256, (200 + 128) % 256))

deep = tile.convert("I").point(lambda v: v * 257).convert("I;16")      # 16-bit greyscale
out = ImageChops.offset(deep, 10, 0)
print("16-bit offset keeps values:", deep.getpixel((0, 0)) == out.getpixel((10, 0)), out.mode)
Output
pixel (0, 0) moved to (128, 128): True
wrap: pixel (200, 200) is now at (72, 72)
16-bit offset keeps values: True I;16

Shifting by half the size brings the four edges together in the middle, which is the standard way to check and fix the seams of a texture that should tile. Before Pillow 13, offset() produced wrong results on 16-bit images; it is also much faster in 13.

Speed

chops_speed.py
import time
from PIL import Image, ImageChops

a = Image.open("photo.jpg").convert("RGB")               # 1600 x 1067
b = a.transpose(Image.Transpose.FLIP_LEFT_RIGHT)


def best(fn):
    runs = []
    for _ in range(7):
        t = time.perf_counter(); fn(); runs.append((time.perf_counter() - t) * 1000)
    return min(runs)


for name, fn in [
    ("difference", lambda: ImageChops.difference(a, b)),
    ("multiply", lambda: ImageChops.multiply(a, b)),
    ("screen", lambda: ImageChops.screen(a, b)),
    ("overlay", lambda: ImageChops.overlay(a, b)),
    ("add", lambda: ImageChops.add(a, b)),
    ("blend", lambda: ImageChops.blend(a, b, 0.5)),
    ("offset", lambda: ImageChops.offset(a, 300, 200)),
    ("getbbox of diff", lambda: ImageChops.difference(a, b).getbbox()),
]:
    print(f"{name:<16}{best(fn):7.2f} ms")
Output
difference         0.79 ms
multiply           6.22 ms
screen             7.32 ms
overlay            9.95 ms
add                4.09 ms
blend              2.14 ms
offset             0.55 ms
getbbox of diff    0.85 ms
ImageChops on two 1600×1067 RGB photos

Shorter is better. Fastest of seven runs, measured by the build. Absolute times depend on the machine.

Show the numbers
Operationms
difference0.79 ms
multiply6.22 ms
screen7.32 ms
overlay9.95 ms
add4.09 ms
blend2.14 ms
offset0.55 ms
getbbox of diff0.85 ms

Every function runs in C on whole images, so a full-photo comparison costs a few milliseconds. Comparing thousands of images is limited by decoding the files, not by ImageChops; decode at reduced size with draft() or thumbnail() if exact pixels do not matter.

All ImageChops functions

Generated from Pillow 13.0.0, so the list and signatures are complete for that version.

ImageChops 21

Name and signatureWhat it does
add(image1, image2, scale=1.0, offset=0)(a + b) / scale + offset, clipped to 0–255. With scale=2.0 it averages two images.
add_modulo(image1, image2)(a + b) % 256: wraps around instead of clipping, so bright plus bright becomes dark.
blend(image1, image2, alpha)a × (1 − alpha) + b × alpha; the same as Image.blend().
composite(image1, image2, mask)Takes each pixel from image1 where mask is white and from image2 where it is black; the same as Image.composite().
constant(image, value)A new L image of the same size, filled with value.
darker(image1, image2)The smaller of the two values per channel (“darken” blend).
difference(image1, image2)|a − b| per channel. All black means identical; getbbox() of it is the changed area.
duplicate(image)A copy of the image; the same as image.copy().
hard_light(image1, image2)Overlay with the roles swapped: the top image decides whether to multiply or screen.
invert(image)255 − value; the same as ImageOps.invert() for 8-bit images (inverting colours).
lighter(image1, image2)The larger of the two values per channel (“lighten” blend).
logical_and(image1, image2)Bitwise AND of two mode 1 images: white only where both are white.
logical_or(image1, image2)Bitwise OR of two mode 1 images: white where either is white.
logical_xor(image1, image2)Bitwise XOR of two mode 1 images: white where exactly one is white.
multiply(image1, image2)a × b / 255: always darker; white leaves the other image unchanged.
offset(image, xoffset, yoffset=None)Shifts the image by (x, y) and wraps the edges around. Fixed for 16-bit images and much faster in Pillow 13.
overlay(image1, image2)Multiplies dark areas and screens light areas of the base image: more contrast.
screen(image1, image2)255 − (255 − a)(255 − b) / 255: always lighter; black leaves the other image unchanged.
soft_light(image1, image2)A gentler overlay: lightens or darkens slightly depending on the top layer.
subtract(image1, image2, scale=1.0, offset=0)(a − b) / scale + offset, clipped to 0–255.
subtract_modulo(image1, image2)(a − b) % 256: wraps around below zero.

Sources

What this page shows comes from running its code with Pillow 13.0.0. The API details and version history were checked against these primary sources:

The outputs and images on this page are the real results of running every example with Pillow 13.0.0 on Python 3.13 (Linux) on 2026-10-29. Every example is also re-run automatically on macOS (Darwin 25.6.0, Pillow 12.3.0), Linux (Linux 6.17.0-1022-azure, Pillow 12.3.0), Windows (Windows 2025Server, Pillow 12.3.0); the line under each example shows the result per operating system. The DejaVu Sans font files sit next to each script so font examples behave the same everywhere. Sample photos: NASA/Sam Lott, public domain. Spotted something wrong? Tell us.