pilgram: Instagram-like Image Filters

2.0.0 · active · verified Thu Apr 16

pilgram is a Python library that applies Instagram-like photo filters, CSS filters, and blend modes to images. It leverages the Pillow library for image manipulation. The current version, 2.0.0, requires Python 3.10+ and Pillow 10.3.0+. The library maintains an active development and release schedule.

Common errors

```
ModuleNotFoundError: No module named 'pilgram'
```
cause The 'pilgram' library is not installed in the current Python environment, or the environment is not activated.

fix Ensure your virtual environment is active and run `pip install pilgram` (or the specific version compatible with your Pillow installation).
```
AttributeError: module 'PIL.ImageMath' has no attribute 'eval'
```
cause This error occurs when `pilgram` version 2.0.0 or higher is used with an older `Pillow` version (specifically, `<10.3.0`) or `pillow-simd`, which lacks `ImageMath.lambda_eval`.

fix Upgrade Pillow to version 10.3.0 or newer (`pip install --upgrade Pillow`). Alternatively, if you must use an older Pillow or `pillow-simd`, uninstall `pilgram` and install `pilgram<2.0.0` (`pip install "pilgram<2.0.0"`).
```
TypeError: fill() takes 1 positional argument but 2 were given
```
cause This indicates an attempt to call the `fill()` function with an outdated signature after upgrading pilgram to version 2.0.0 or later, where the function's parameters were modified.

fix Update your code to match the new signature of the `fill()` function as introduced in pilgram v2.0.0. Refer to the official documentation or source code for the correct usage.
```
RuntimeError: The _imagingft C module is not installed
```
cause This error usually originates from Pillow, which `pilgram` depends on. It means that a required C extension for font handling in Pillow was not correctly compiled or installed. This can happen in environments where build tools are missing, or dependencies like FreeType are not present during Pillow's installation.

fix Reinstall Pillow after ensuring that necessary build dependencies are available on your system. For Debian/Ubuntu: `sudo apt-get update && sudo apt-get install libimage-exiftool-perl libraqm-dev libjpeg-dev zlib1g-dev liblcms2-dev libwebp-dev libtiff5-dev libfreetype6-dev libharfbuzz-dev libfribidi-dev tcl8.6-dev tk8.6-dev python3-tk`. For macOS: `brew install libjpeg zlib libtiff webp little-cms2 freetype harfbuzz fribidi` then reinstall `pip install --no-binary :all: Pillow`.

Warnings

breaking pilgram v2.0.0 dropped support for Python versions older than 3.10 and Pillow versions older than 10.3.0. It also no longer supports `pillow-simd`.
Fix: Upgrade Python to 3.10 or newer, and Pillow to 10.3.0 or newer. If using `pillow-simd` or older Pillow, you must pin `pilgram<2.0.0` during installation.
breaking In pilgram v2.0.0, the internal implementation changed from `ImageMath.eval` to `ImageMath.lambda_eval`. This specifically breaks compatibility with `pillow-simd` and older Pillow versions which do not provide `ImageMath.lambda_eval`.
Fix: Ensure Pillow >= 10.3.0 is installed. If you rely on `pillow-simd` or need to use older Pillow versions, you must install `pilgram<2.0.0`.
breaking The signature for the `fill` function within pilgram has been changed in v2.0.0, specifically removing a list from its signature.
Fix: Consult the latest pilgram documentation or source for the updated `fill` function signature and adjust your code accordingly. Old usages will result in `TypeError`.
deprecated Python 2.x support was officially dropped with pilgram v1.2.0. Attempting to install or run pilgram on Python 2.x will fail.
Fix: Migrate your project to Python 3. If you must use Python 2.x, use `pilgram<1.2.0`.
gotcha Pillow compatibility is crucial for pilgram. Installing an incompatible version of Pillow with pilgram can lead to `AttributeError` or other runtime issues.
Fix: Always install Pillow and pilgram according to the recommended version selection guide. For pilgram >= 2.0.0, use Pillow >= 10.3.0. For pilgram < 2.0.0, use Pillow < 10.3.0 or `pillow-simd`.

Install

pip install "Pillow>=10.3.0" numpy pilgram Recommended (Latest pilgram and Pillow)
pip install "Pillow<10.3.0" numpy "pilgram<2.0.0" For older Pillow versions or Pillow-SIMD (pilgram<2.0.0)

Imports

Image
```
from PIL import Image
```
pilgram
```
import pilgram
```
pilgram.css
```
import pilgram.css
```
pilgram.css.blending
```
import pilgram.css.blending
```

Quickstart

This example demonstrates how to load an image, apply an Instagram-like filter, a CSS filter, and a blend mode. It creates dummy images if input files are not found, ensuring the code is runnable out-of-the-box.

from PIL import Image
import pilgram
import os

# Create a dummy image if 'sample.jpg' does not exist
if not os.path.exists('sample.jpg'):
    print("Creating dummy 'sample.jpg' for demonstration.")
    img = Image.new('RGB', (600, 400), color = 'red')
    img.save('sample.jpg')

# Load an image
im = Image.open('sample.jpg')

# Apply an Instagram-like filter (e.g., Aden)
pilgram.aden(im).save('sample-aden.jpg')
print("Applied 'aden' filter, saved as 'sample-aden.jpg'")

# Apply a CSS filter (e.g., sepia)
import pilgram.css
pilgram.css.sepia(im).save('sample-sepia.jpg')
print("Applied CSS 'sepia' filter, saved as 'sample-sepia.jpg'")

# Apply a blend mode (requires two images)
if not os.path.exists('backdrop.jpg'):
    print("Creating dummy 'backdrop.jpg' for demonstration.")
    backdrop = Image.new('RGB', (600, 400), color = 'blue')
    backdrop.save('backdrop.jpg')
else:
    backdrop = Image.open('backdrop.jpg')

if not os.path.exists('source.jpg'):
    print("Creating dummy 'source.jpg' for demonstration.")
    source = Image.new('RGB', (600, 400), color = 'green')
    source.save('source.jpg')
else:
    source = Image.open('source.jpg')

import pilgram.css.blending
pilgram.css.blending.color(backdrop, source).save('blending.jpg')
print("Applied 'color' blend mode, saved as 'blending.jpg'")

view raw JSON →