pilgram

A python library for instagram filters.

The filter implementations are inspired by CSSgram.

Requirements

• Python >= 3.10
• Pillow or pillow-simd
• NumPy

Pillow Compatibility Notes

Important: This library requires specific Pillow versions for optimal compatibility:

• Pillow >= 10.3.0: Use latest pilgram version for full feature support including ImageMath.lambda_eval
• Pillow < 10.3.0: Use pilgram<2.0.0 which supports older Pillow versions with ImageMath.eval
• pillow-simd: Use pilgram<2.0.0 (pillow-simd lacks ImageMath.lambda_eval support)

Version Selection Guide

# For Pillow >= 10.3.0
pip install pillow>=10.3.0
pip install pilgram  # Latest version

# For Pillow < 10.3.0 or pillow-simd
pip install pillow<10.3.0  # or pillow-simd
pip install "pilgram<2.0.0"

Install

Recommended (Latest Pillow)

pip install pillow>=10.3.0
pip install numpy
pip install pilgram  # Latest version with ImageMath.lambda_eval support

For Older Pillow Versions

pip install pillow<10.3.0  # or pillow-simd
pip install numpy
pip install "pilgram<2.0.0"  # Last version supporting ImageMath.eval

Usage

Available instagram filters on pilgram:

• _1977
• aden
• brannan
• brooklyn
• clarendon
• earlybird
• gingham
• hudson
• inkwell
• kelvin
• lark
• lofi
• maven
• mayfair
• moon
• nashville
• perpetua
• reyes
• rise
• slumber
• stinson
• toaster
• valencia
• walden
• willow
• xpro2

from PIL import Image
import pilgram

im = Image.open('sample.jpg')
pilgram.aden(im).save('sample-aden.jpg')

Similarly, pilgram provides css filters and blend modes as a by-product.

Available css filters on pilgram.css:

• contrast
• grayscale
• hue_rotate
• saturate
• sepia

from PIL import Image
import pilgram.css

im = Image.open('sample.jpg')
pilgram.css.sepia(im).save('sample-sepia.jpg')

Available blend modes on pilgram.css.blending:

• color
• color_burn
• color_dodge
• darken
• difference
• exclusion
• hard_light
• hue
• lighten
• multiply
• normal
• overlay
• screen
• soft_light

from PIL import Image
import pilgram.css.blending

backdrop = Image.open('backdrop.jpg')
source = Image.open('source.jpg')
pilgram.css.blending.color(backdrop, source).save('blending.jpg')

Demo

• notebooks/example.ipynb

Filter performance comparison with instagram-filters

• notebooks/filter-performance-comparison.ipynb

Development

Setup development environment

# Install uv (if not already installed)
curl -LsSf https://astral.sh/uv/install.sh | sh

# Clone the repository
git clone https://github.com/akiomik/pilgram.git
cd pilgram

# Install dependencies (including dev dependencies)
uv sync --all-extras

# Install Pillow or pillow-simd (choose one)
uv add pillow>=9.3.0  # or uv add pillow-simd

Run commands

make check       # Run all checks (lint + format-check + type-check + test)
make test        # Run tests only
make lint        # Run ruff linting
make format      # Format code with ruff
make test-benchmark  # Run performance benchmarks