---
id: blend-modes
version: "2.2.0"
license: MIT
license_treatment: permissive
maintenance: active
---

# blend-modes — Image processing blend modes

License: permissive · Maintenance: active · Downloads: 153.5K/mo

## What it is and what it does

Blend Modes is a NumPy-based image compositing library that applies blend modes—the layer-blending algorithms used in graphics editors—to combine two images. It supports fourteen modes including soft light, dodge, multiply, overlay, and grain extract, each producing different visual effects by controlling how pixel values from a foreground layer mix with a background layer. You pass two same-sized NumPy arrays (in RGBA format with float values 0–255) and an opacity parameter; the function returns a blended array in the same format.

The package is designed for speed through NumPy vectorization and integrates easily with image-loading libraries like Pillow or OpenCV. It's useful when you need programmatic control over layer blending in image processing pipelines—tasks that would otherwise require calling external graphics software or reimplementing blend algorithms yourself.

Use it for:

- Composite multiple image layers in batch image processing pipelines with control over blend mode and opacity.
- Apply Photoshop-style blend modes to images loaded via Pillow or OpenCV without leaving Python.
- Generate image effects (dodge, multiply, overlay) programmatically for graphics generation or photo editing tools.
- Blend watermarks, overlays, or annotations onto background images with precise blending control.
- Implement layer-based image editing in custom graphics applications.

## Worth the install?

AI-flagged interpretation of the facts above — verify before relying.

Implements blend modes (soft light, dodge, multiply, overlay, and others) for compositing image layers using NumPy arrays, mirroring functionality found in graphics software like Photoshop and GIMP.

Yes. The package is stable, actively maintained, has no known vulnerabilities, installs with minimal friction (NumPy only), and fills a genuine gap for programmatic image blending. Install it if you need to composite images with blend modes in Python; skip it if you only need basic image overlay without blend mode control.

## Install

pip install blend-modes
uv add blend-modes
poetry add blend-modes

## Installing blend-modes

Before you install: Low friction: pure Python wheel with only NumPy as a runtime dependency. Actively maintained with recent commits and a stable release history since 2016.

License in practice: MIT license is permissive; you can use, modify, and distribute this package freely in commercial and private projects with minimal restrictions.

Quickstart:

pip install blend_modes

from blend_modes import soft_light
import numpy as np

# Assuming bg_img and fg_img are numpy float arrays with shape (height, width, 4)
blended = soft_light(bg_img, fg_img, opacity=0.7)

Input images must be NumPy float arrays in RGBA format with shape (height, width, 4) and values in range 0.0–255.0; both images must have identical dimensions.

Verify before relying:

- Whether Cython optimization mentioned in the description is available or planned as a separate package.
- Current Python version support (classifiers list 3.5 but requires_python is unspecified).

## Package facts

- License: MIT (permissive)
- Python support: unspecified
- Install friction: low
- Maintenance: active
- Downloads: 153.5K/month (top 15,000 on PyPI)
- Known vulnerabilities: none known

## Tags

image blend modes, layer blending, image compositing, soft light dodge multiply, photoshop blend modes python, image layer mixing, numpy image blending, image-processing, graphics-compositing

[View on SkillFed](https://skillfed.io/packages/blend-modes) · [View on PyPI](https://pypi.org/project/blend-modes/)