---
id: pilgram
version: "2.0.0"
license: Apache-2.0
license_treatment: permissive
maintenance: active
---

# pilgram — library for instagram filters

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

## What it is and what it does

Pilgram is a Python library that applies Instagram-style photo filters to images using Pillow and NumPy. It implements named filters inspired by the CSSgram project, plus a set of CSS-based filters (contrast, grayscale, hue_rotate, saturate, sepia) and blend modes for image compositing. The library works by transforming image pixel data through filter matrices and blending operations.

You use it by opening an image, calling a filter function from pilgram, and saving the result. It's designed for batch image processing, data augmentation in machine learning workflows, or any scenario where you need to apply consistent stylized effects to photos. The current version requires Python >= 3.10 and Pillow >= 10.3.0, with backward-compatible older versions available for earlier Pillow releases.

Use it for:

- Apply Instagram-style filters to batches of photos for social media or portfolio preprocessing.
- Generate augmented training data for machine learning by applying multiple filter variations to images.
- Composite images using blend modes for photo editing workflows.
- Add CSS-based effects like sepia or grayscale to images in automated image processing pipelines.
- Create consistent visual styling across image datasets by applying the same named filter to all images.

## Worth the install?

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

Applies Instagram-style filters and CSS-based image effects to images using NumPy and Pillow, including blend modes for compositing.

Yes. Low install friction, active maintenance, no known vulnerabilities, permissive Apache-2.0 license, and a focused scope make it a safe choice. Install if you need Instagram-style filters or CSS-based image effects; the Pillow version requirement (>= 10.3.0) is the only real constraint, but older pilgram versions exist for earlier Pillow releases.

## Install

pip install pilgram
uv add pilgram
poetry add pilgram

## Installing pilgram

Before you install: Low friction: pure Python wheel with only NumPy and Pillow as runtime dependencies. Actively maintained as of 2026-08-10 with recent release. Requires Python >= 3.10 and Pillow >= 10.3.0 for current version; older pilgram versions available for earlier Pillow releases.

License in practice: Apache-2.0 permissive license allows commercial and private use with minimal restrictions, making it safe for most projects.

Quickstart:

import pilgram
from pillow import Image

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

Requires Pillow >= 10.3.0 for version 2.0.0; use pilgram<2.0.0 with older Pillow versions or pillow-simd.

Verify before relying:

- Exact count of named filters available in the library.
- Performance characteristics compared to other Instagram filter libraries at scale.
- Whether ImageMath.lambda_eval requirement in Pillow 10.3.0+ represents a breaking change for existing workflows.

## Package facts

- License: Apache-2.0 (permissive)
- Python support: supports_current
- Install friction: low
- Maintenance: active
- Downloads: 155.7K/month (top 15,000 on PyPI)
- Known vulnerabilities: none known

## Tags

instagram filters python, image filter library, css filters pillow, image blending modes, photo effects python, image processing filters, instagram-style effects, image-processing, data-augmentation

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