How to Merge Two Images in Python Easily

You can merge two images in Python using the Pillow library by opening both images and pasting one onto the other with Image.paste(). This method lets you combine images by overlaying or placing them side by side.

Syntax

To merge two images, you first open them with Image.open(). Then, use Image.paste() to place one image onto the other at a specific position. Finally, save or show the merged image.

• Image.open(path): Opens an image file.
• Image.paste(image, position, mask): Pastes image onto the base image at position (x, y coordinates) using an optional mask for transparency.
• Image.save(path): Saves the merged image to a file.

python

from PIL import Image

base_image = Image.open('base.jpg')
overlay_image = Image.open('overlay.png')

x, y = 0, 0  # specify position
base_image.paste(overlay_image, (x, y), overlay_image)  # use overlay_image as mask for transparency
base_image.save('merged.jpg')

Example

This example opens two images, resizes the overlay to fit, and pastes it onto the base image at position (50, 50). It then saves and shows the merged result.

python

from PIL import Image

# Open base image
base = Image.open('base.jpg')

# Open overlay image
overlay = Image.open('overlay.png')

# Resize overlay to smaller size
overlay = overlay.resize((100, 100))

# Paste overlay onto base at position (50, 50) with transparency
base.paste(overlay, (50, 50), overlay)

# Save merged image
base.save('merged_output.jpg')

# Show merged image
base.show()

Output

A window opens displaying the merged image with the overlay placed on the base image at (50, 50).

Common Pitfalls

Common mistakes include:

• Not using the overlay image as a mask in paste(), which causes the overlay to cover the base image without transparency.
• Trying to paste images of different modes (like RGB and RGBA) without conversion.
• Not resizing images to fit, causing unexpected overlaps or cropping.

Always ensure the overlay image has an alpha channel (transparency) and pass it as the third argument to paste() for proper merging.

python

from PIL import Image

base = Image.open('base.jpg')
overlay = Image.open('overlay.png')

# Wrong: no mask, overlay covers base fully
base.paste(overlay, (50, 50))  # No transparency

# Right: use overlay as mask for transparency
base.paste(overlay, (50, 50), overlay)

Quick Reference

Function	Purpose
Image.open(path)	Open an image file
Image.paste(image, position, mask)	Paste image onto another with optional transparency mask
Image.resize(size)	Resize image to given size (width, height)
Image.save(path)	Save image to file
Image.show()	Display image in default viewer

Key Takeaways

Use Pillow's Image.paste() with a mask to merge images with transparency.

Resize images before merging to control their size and placement.

Ensure images have compatible modes (e.g., RGBA) for proper merging.

Always pass the overlay image as the mask in paste() to keep transparency.

Save or show the merged image after combining.