{"id":8418,"library":"pilgram","title":"pilgram: Instagram-like Image Filters","description":"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.","status":"active","version":"2.0.0","language":"en","source_language":"en","source_url":"https://github.com/akiomik/pilgram","tags":["image processing","filters","instagram","Pillow","PIL","photography"],"install":[{"cmd":"pip install \"Pillow>=10.3.0\" numpy pilgram","lang":"bash","label":"Recommended (Latest pilgram and Pillow)"},{"cmd":"pip install \"Pillow<10.3.0\" numpy \"pilgram<2.0.0\"","lang":"bash","label":"For older Pillow versions or Pillow-SIMD (pilgram<2.0.0)"}],"dependencies":[{"reason":"Core image manipulation library. Version compatibility is critical for pilgram versions.","package":"Pillow","optional":false},{"reason":"Used for numerical operations, specifically array manipulation within image processing.","package":"numpy","optional":false}],"imports":[{"symbol":"Image","correct":"from PIL import Image"},{"symbol":"pilgram","correct":"import pilgram"},{"symbol":"pilgram.css","correct":"import pilgram.css"},{"symbol":"pilgram.css.blending","correct":"import pilgram.css.blending"}],"quickstart":{"code":"from PIL import Image\nimport pilgram\nimport os\n\n# Create a dummy image if 'sample.jpg' does not exist\nif not os.path.exists('sample.jpg'):\n    print(\"Creating dummy 'sample.jpg' for demonstration.\")\n    img = Image.new('RGB', (600, 400), color = 'red')\n    img.save('sample.jpg')\n\n# Load an image\nim = Image.open('sample.jpg')\n\n# Apply an Instagram-like filter (e.g., Aden)\npilgram.aden(im).save('sample-aden.jpg')\nprint(\"Applied 'aden' filter, saved as 'sample-aden.jpg'\")\n\n# Apply a CSS filter (e.g., sepia)\nimport pilgram.css\npilgram.css.sepia(im).save('sample-sepia.jpg')\nprint(\"Applied CSS 'sepia' filter, saved as 'sample-sepia.jpg'\")\n\n# Apply a blend mode (requires two images)\nif not os.path.exists('backdrop.jpg'):\n    print(\"Creating dummy 'backdrop.jpg' for demonstration.\")\n    backdrop = Image.new('RGB', (600, 400), color = 'blue')\n    backdrop.save('backdrop.jpg')\nelse:\n    backdrop = Image.open('backdrop.jpg')\n\nif not os.path.exists('source.jpg'):\n    print(\"Creating dummy 'source.jpg' for demonstration.\")\n    source = Image.new('RGB', (600, 400), color = 'green')\n    source.save('source.jpg')\nelse:\n    source = Image.open('source.jpg')\n\nimport pilgram.css.blending\npilgram.css.blending.color(backdrop, source).save('blending.jpg')\nprint(\"Applied 'color' blend mode, saved as 'blending.jpg'\")","lang":"python","description":"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."},"warnings":[{"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.","message":"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`.","severity":"breaking","affected_versions":">=2.0.0"},{"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`.","message":"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`.","severity":"breaking","affected_versions":">=2.0.0"},{"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`.","message":"The signature for the `fill` function within pilgram has been changed in v2.0.0, specifically removing a list from its signature.","severity":"breaking","affected_versions":">=2.0.0"},{"fix":"Migrate your project to Python 3. If you must use Python 2.x, use `pilgram<1.2.0`.","message":"Python 2.x support was officially dropped with pilgram v1.2.0. Attempting to install or run pilgram on Python 2.x will fail.","severity":"deprecated","affected_versions":">=1.2.0"},{"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`.","message":"Pillow compatibility is crucial for pilgram. Installing an incompatible version of Pillow with pilgram can lead to `AttributeError` or other runtime issues.","severity":"gotcha","affected_versions":"All"}],"env_vars":null,"last_verified":"2026-04-16T00:00:00.000Z","next_check":"2026-07-15T00:00:00.000Z","problems":[{"fix":"Ensure your virtual environment is active and run `pip install pilgram` (or the specific version compatible with your Pillow installation).","cause":"The 'pilgram' library is not installed in the current Python environment, or the environment is not activated.","error":"ModuleNotFoundError: No module named 'pilgram'"},{"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\"`).","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`.","error":"AttributeError: module 'PIL.ImageMath' has no attribute 'eval'"},{"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.","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.","error":"TypeError: fill() takes 1 positional argument but 2 were given"},{"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`.","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.","error":"RuntimeError: The _imagingft C module is not installed"}]}