Easy Thumbnails for Django

2.10.1 · active · verified Tue Apr 14

Easy Thumbnails is a powerful yet user-friendly Django application designed for generating and managing image thumbnails. It dynamically creates thumbnails based on a source image, supports predefined aliases, and integrates seamlessly with Django models and templates. The library is actively maintained, with the current stable version being 2.10.1, and releases occurring regularly to support new Django and Python versions.

Warnings

breaking Version 2.10.0 dropped support for Python 3.8 and Django 4.1 and earlier. Ensure your project meets the new minimum requirements.
Fix: Upgrade Python to 3.9+ and Django to 4.2+ (Django 5.1+ supported).
breaking Version 2.8.0 removed the `THUMBNAIL_HIGH_RESOLUTION` and `THUMBNAIL_HIGHRES_INFIX` settings. High-resolution support is now handled differently, if still needed, consult the latest documentation for alternatives.
Fix: Remove these settings from your `settings.py`. Review documentation for retina/high-DPI display handling if previously used.
gotcha If you use multiple thumbnailing libraries (e.g., `sorl-thumbnail` and `easy-thumbnails`) in the same project, the default `{% load thumbnail %}` template tag might clash.
Fix: Use `{% load easy_thumbnails_tags %}` instead of `{% load thumbnail %}` for `easy-thumbnails` in your templates to avoid conflicts.
gotcha When using remote storage backends (e.g., S3), fetching image dimensions can be slow. This can impact performance for pages rendering many thumbnails.
Fix: Enable `THUMBNAIL_SAVE_DIMENSIONS = True` in your `settings.py` to store thumbnail dimensions in the database, reducing calls to remote storage.
deprecated Version 2.8.4 replaced deprecated Pillow constants against newer counterparts. While this is an internal change, older custom processors or direct Pillow interactions might need adjustment.
Fix: Ensure your Pillow library is up-to-date and review any custom image processing logic for compatibility with newer Pillow versions.

Install

pip install easy-thumbnails Install stable version

Imports

ThumbnailerImageField

from easy_thumbnails.fields import ThumbnailerImageField

get_thumbnailer

from easy_thumbnails.files import get_thumbnailer

template_tag_load
```
{% load thumbnail %}
```
While {% load thumbnail %} is common, if conflicting with other thumbnail libraries, use {% load easy_thumbnails_tags %} to avoid clashes.

Quickstart

After installing and adding 'easy_thumbnails' to `INSTALLED_APPS`, run migrations. Define thumbnail aliases in `THUMBNAIL_ALIASES` in your `settings.py` for reusable thumbnail configurations. Integrate `ThumbnailerImageField` into your models. In templates, load the `thumbnail` tags and use the `thumbnail_url` filter with an alias, or the `thumbnail` tag with explicit size and options. For programmatic access, use `get_thumbnailer`.

import os

# settings.py
INSTALLED_APPS = [
    # ...
    'easy_thumbnails',
]

THUMBNAIL_ALIASES = {
    '': {
        'avatar': {'size': (50, 50), 'crop': True},
        'profile_square': {'size': (200, 200), 'crop': 'smart'},
    },
}

# models.py
from django.db import models
from easy_thumbnails.fields import ThumbnailerImageField

class Profile(models.Model):
    user = models.OneToOneField('auth.User', on_delete=models.CASCADE)
    photo = ThumbnailerImageField(upload_to='profile_photos', blank=True, null=True)

    def __str__(self):
        return self.user.username

# In a Django template (e.g., profile.html)
# {% load thumbnail %}
# <img src="{{ profile.photo|thumbnail_url:'avatar' }}" alt="{{ profile.user.username }} avatar" />

# Or, with custom options directly in template
# {% load thumbnail %}
# <img src="{% thumbnail profile.photo 100x100 crop %}" alt="Profile photo" />

# In Python code
# from easy_thumbnails.files import get_thumbnailer
# profile_instance = Profile.objects.get(pk=1)
# if profile_instance.photo:
#     thumbnailer = get_thumbnailer(profile_instance.photo)
#     avatar_url = thumbnailer['avatar'].url
#     print(f"Avatar URL: {avatar_url}")

# Run migrations after adding to INSTALLED_APPS and defining models:
# python manage.py migrate easy_thumbnails

view raw JSON →