Pages

Topics

Tools

↑↓navigate↵openescclose
All guides

Python Pillow: Combining Images with paste, blend, and alpha_composite

Learn how to combine images with Python Pillow using paste for placement, blend for cross-fades, and alpha_composite for per-pixel transparency.

~5 min readPython
#Pillow#image processing#image composition#alpha blending
Illustration of two overlapping images with a transparent layer being composited using Python Pillow

When you need to combine images in Python, Pillow offers several methods. The most common are paste(), blend(), and alpha_composite(), and composite() adds mask-driven control. Each method suits a different composition scenario: positional placement, uniform transparency, per-pixel alpha blending, or mask-based transitions. This article walks through each method with concrete examples, then covers masking, mode compatibility, and the performance considerations that matter when working with large images.

Pasting Images at Specific Coordinates

The most direct way to combine images is Image.paste(). It copies one image onto another at given coordinates, replacing the pixels in the destination region. The method does not perform any blending; it simply overwrites.

python
from PIL import Image background = Image.new("RGB", (800, 600), "white") foreground = Image.open("logo.png") # Paste the foreground at (100, 150) background.paste(foreground, (100, 150)) background.save("composed.jpg")

If the foreground has an alpha channel, paste() ignores it unless you supply a mask. Without a mask, the foreground's RGB values are copied directly, so transparent areas can appear as black or as whatever RGB data is stored in those pixels. To preserve transparency, pass a mask that indicates which pixels to copy.

python
background.paste(foreground, (100, 150), mask=foreground)

Here the mask is the foreground image itself; Pillow uses the alpha channel of the mask to determine the opacity of each pixel. This works because paste() accepts a mask that can be an image with mode "1", "L", or "RGBA". When the mask is an RGBA image, only its alpha channel is used.

Alpha Compositing with alpha_composite()

For true alpha compositing, where the source and destination are combined based on their alpha values, use Image.alpha_composite(). This method expects both images to be in RGBA mode and performs the standard Porter-Duff "over" operation. The result is a new image where the source is drawn over the destination, respecting per-pixel alpha.

python
from PIL import Image background = Image.open("background.png").convert("RGBA") foreground = Image.open("overlay.png").convert("RGBA") composed = Image.alpha_composite(background, foreground) composed.save("composed.png")

Unlike paste(), alpha_composite() does not take coordinates. Both images must be the same size. If you need to place a smaller image at a specific position, you must first create a transparent canvas of the background size, paste the smaller image onto it, and then composite.

python
canvas = Image.new("RGBA", background.size, (0, 0, 0, 0)) canvas.paste(foreground, (100, 150), mask=foreground) composed = Image.alpha_composite(background, canvas)

Because paste() ignores the alpha channel unless a mask is supplied, passing mask=foreground keeps the foreground's transparency when copying it onto the canvas.

Uniform Blending with blend()

Image.blend() creates a new image by linearly interpolating between two images of the same size and mode. The alpha parameter controls the weight of the first image: alpha=0 returns the first image, alpha=1 returns the second, and values in between produce a cross-fade.

python
from PIL import Image img1 = Image.open("photo1.jpg").convert("RGB") img2 = Image.open("photo2.jpg").convert("RGB") blended = Image.blend(img1, img2, alpha=0.5) blended.save("blended.jpg")

This is useful for creating transitions or comparing two versions of an image, but it applies the same alpha to every pixel. There is no spatial variation. If you need a gradient blend across the image, you would have to build a mask and use composite() or paste() with a mask.

Selective Composition with Masks

For more control, use Image.composite(). It takes two images and a mask, and returns an image where each pixel is chosen from the first or second image based on the mask's intensity. The mask can be an image with mode "1", "L", or "RGBA"; its pixel values determine the blend factor at each location.

python
from PIL import Image, ImageDraw base = Image.open("base.jpg").convert("RGB") overlay = Image.open("overlay.jpg").convert("RGB") # Create a vertical gradient mask mask = Image.new("L", base.size, 0) draw = ImageDraw.Draw(mask) for y in range(base.height): draw.line([(0, y), (base.width, y)], fill=int(255 * y / base.height)) result = Image.composite(base, overlay, mask) result.save("composite.jpg")

Here the mask controls the transition from the base image at the top to the overlay at the bottom. This is far more flexible than blend() because the mixing ratio varies per pixel. You can generate masks from shapes, text, or any other image processing operation.

Mode and Size Compatibility

Mode and size compatibility depends on the method. paste() can copy between different modes, but the result may be unexpected if you paste an RGBA image onto an RGB background without a mask. blend() and alpha_composite() require both images to have the same mode and size; composite() also requires the two images and the mask to be the same size. Otherwise, Pillow raises a ValueError.

A common mistake is trying to alpha_composite() an RGB image with an RGBA one. Convert both to RGBA first:

python
background = background.convert("RGBA") foreground = foreground.convert("RGBA")

For paste(), the mask must be in mode "1", "L", or "RGBA". If you use an RGBA image as a mask, only its alpha channel is considered. This can be confusing when the mask has transparency but also color; the color is ignored.

Performance and Memory Considerations

When combining large images, memory usage can become a concern. Each Image object holds pixel data in memory, and operations like alpha_composite() create a new image of the same size. If you are processing many images, consider working in chunks or using Image.paste() with a mask, which can be more efficient than creating an intermediate canvas for every overlay.

For repeated compositing in a loop, avoid reloading the same background image from disk each time. Keep it in memory and reuse it. Also, be aware that convert("RGBA") creates a new image, so if you need the original mode later, retain a reference.

A practical tip: if you only need to overlay a small image onto a large one, using paste() with a mask is usually faster than creating a full-size canvas and calling alpha_composite(). The canvas approach allocates a new image the size of the background, which can be wasteful when the foreground is small. Measure your specific workload to decide, but in general, paste() is the lighter operation.

Handling Edge Cases in Composition

One common edge case is pasting an image partially outside the background bounds. paste() clips the foreground to the background's boundaries without raising an error. This is useful for sliding animations, but if you need to know the visible region, compute the intersection manually.

Another issue arises when you pass an RGB image as a mask. paste() only accepts masks with mode "1", "L", or "RGBA", so an RGB image is rejected. If the foreground is RGBA, you can pass it directly as the mask, or extract its alpha channel with split():

python
r, g, b, a = foreground.split() background.paste(foreground, (0, 0), mask=a)

Finally, remember that paste() modifies the destination image in place, while blend(), alpha_composite(), and composite() return new images. If you need to keep the original background unchanged, work on a copy with background.copy() before pasting.

Try matching browser tools

All tools

Small utilities that fit Python work — they run entirely in this browser tab, so nothing you paste leaves your device.

All Python guides

More in Python

All Python guides

The guides filed next to this one in Python, in library order.