Python:Pillow .alpha_composite()

yusupscopes's avatar
yusupscopes's avatar
yusupscopes
Published Mar 20, 2025
Contribute to Docs

In Pillow, the .alpha_composite() method merges two images by overlaying the foreground onto the background using their alpha (transparency) channels. It returns a new image with the composite result.

  • Career path

    Computer Science

    Looking for an introduction to the theory behind programming? Master Python while learning data structures, algorithms, and more!
    • Includes 6 Courses
    • With Professional Certification
    • Beginner Friendly.
      75 hours
  • Course

    Learn Python 3

    Learn the basics of Python 3.12, one of the most powerful, versatile, and in-demand programming languages today.
    • With Certificate
    • Beginner Friendly.
      24 hours

Syntax

PIL.Image.alpha_composite(image1, image2)

Parameters:

  • image1 (Image): The background image, which must be in RGBA mode.
  • image2 (Image): The foreground image, which must also be in RGBA mode.

Return value:

Returns a new RGBA image with the composite result.

Note: The .alpha_composite() method requires both image1 and image2 parameters to have the same dimensions (width and height); otherwise, it won’t work as expected.

Example

The following example demonstrates the use of the .alpha_composite() method:

from PIL import Image


# Open background and foreground images
background = Image.open("ocean.png").convert("RGBA")
foreground = Image.open("ship.png").convert("RGBA")


# Composite the images
result = Image.alpha_composite(background, foreground)


# Display and save the result
result.show()
result.save('ship-on-ocean.png')

Original Background Image:

Original background image is the image of an ocean with sun and clouds in the sky.

Original Foreground Image:

Original foreground image is the image of a ship.

Result Composite Image:

The resulting composite image shows the ship on the ocean.

All contributors

Contribute to Docs

Learn Python:Pillow on Codecademy

  • Career path

    Computer Science

    Looking for an introduction to the theory behind programming? Master Python while learning data structures, algorithms, and more!
    • Includes 6 Courses
    • With Professional Certification
    • Beginner Friendly.
      75 hours
  • Course

    Learn Python 3

    Learn the basics of Python 3.12, one of the most powerful, versatile, and in-demand programming languages today.
    • With Certificate
    • Beginner Friendly.
      24 hours