Usage

The common way easy-thumbnails is used is via the {% thumbnail %} template tag or thumbnail_url filter, which generates images from a model with an ImageField. The tag can also be used with media images not tied to a specific model by passing in the relative path instead.

Custom database fields are also available for simpler access.

The underlying Python code can be used for lower-level generation of thumbnail images.

Overview

The primary function of easy-thumbnails is to dynamically create thumbnails based on a source image.

So whenever a thumbnail does not exist or if the source was modified more recently than the existing thumbnail, a new thumbnail is generated (and saved).

Thumbnail aliases can be defined in the THUMBNAIL_ALIASES setting, providing predefined thumbnail options. This also allows for generation of thumbnails when the source image is uploaded.

Thumbnail options

To generate a thumbnail of a source image, you specify options which are used by the image processors to generate the required image.

size is a required option, and defines the bounds that the generated image must fit within.

Other options are only provided if the given functionality is required:

  • quality=<N> where N is an integer between 1 and 100 specifying output JPEG quality. The default is 85.
  • subsampling=<N> sets the JPEG color subsampling level where N is:
    • 2 is 4:1:1 (both easy-thumbnails and PIL’s default)
    • 1 is 4:2:2 (slightly crisper color borders, small increase in size)
    • 0 is 4:4:4 (very crisp color borders, ~15% increase in size)
  • autocrop removes any unnecessary whitespace from the edges of the source image.
  • bw converts the image to grayscale.
  • replace_alpha=#colorcode replaces any transparency layer with a solid color.
  • crop=<smart|scale|W,H> cuts the edges of the image to match the aspect ratio of size before resizing.
    • smart means the image is incrementally cropped down to the requested size by removing slices from edges with the least entropy.
    • scale means at least one dimension fits within the size dimensions given.
    • W,H modifies the cropping origin behavior:
      • crop="0,0" will crop from the left and top edges.
      • crop="-10,-0" will crop from the right edge (with a 10% offset) and the bottom edge.
      • crop=",0" will keep the default behavior for the x axis (horizontally centering the image) and crop from the top edge.

For a complete and detailed list of options, see the Image Processors reference documentation.

To change a default options level, add it to the THUMBNAIL_DEFAULT_OPTIONS setting. Be aware that this will change the filename for thumbnails, so existing thumbnails which don’t explicitly specify the new default option will have a new filename (and therefore be regenerated).

Thumbnail aliases

An alias is a specific set of thumbnail options.

Using aliases gives you a single location to define all of your standard thumbnail sizes/options, and avoids repetition of thumbnail options in your code and templates.

An alias may be available project-wide, or set to target a specific app, model or field.

The setting is defined like this:

THUMBNAIL_ALIASES = {
    <target>: {
        <alias name>: <alias options dictionary>,
        ...
    },
    ...
}

Use the target '' for project-wide aliases. Otherwise, the target should be a string which defines the scope of the contained aliases:

  • 'sprocket.Widget.image' would make the aliases available to only the ‘image’ field of a ‘Widget’ model in an app named ‘sprocket’.
  • 'sprocket.Widget' would apply to any field in the ‘Widget’ model.
  • 'sprocket' would target any field in any model in the app.

Pregeneration

Some provided signal handlers (along with a new saved_file signal) allow for you to have the relevant aliases generated when a file is uploaded.

easy_thumbnails.signal_handlers.generate_aliases(fieldfile, **kwargs)

A saved_file signal handler which generates thumbnails for all field, model, and app specific aliases matching the saved file’s field.

easy_thumbnails.signal_handlers.generate_aliases_global(fieldfile, **kwargs)

A saved_file signal handler which generates thumbnails for all field, model, and app specific aliases matching the saved file’s field, also generating thumbnails for each project-wide alias.

In a module that will be executed when Django loads (such as a models.py file), register one of these signal handlers. For example:

from easy_thumbnails.signals import saved_file
from easy_thumbnails.signal_handlers import generate_aliases_global

saved_file.connect(generate_aliases_global)

Asynchronous Pregeneration

For some use cases, it may not be necessary to have the relevant aliases generated at the exact moment a file is uploaded. As an alternative, the pregeneration task can be queued and executed by a background process.

The following example uses django-celery in conjunction with Celery to achieve this.

models.py:

from django.dispatch import receiver
from easy_thumbnails.signals import saved_file
from myapp import tasks

@receiver(saved_file)
def generate_thumbnails_async(sender, fieldfile, **kwargs):
    tasks.generate_thumbnails.delay(
        model=sender, pk=fieldfile.instance.pk,
        field=fieldfile.field.name)

tasks.py:

from celery import task
from easy_thumbnails.files import generate_all_aliases

@task
def generate_thumbnails(model, pk, field):
    instance = model._default_manager.get(pk=pk)
    fieldfile = getattr(instance, field)
    generate_all_aliases(fieldfile, include_global=True)

This results in a more responsive experience for the user, particularly when dealing with large files and/or remote storage.

Setting aliases for your third-party app

If you have a distributable app that uses easy-thumbnails and want to provide an alias, you can modify the aliases at runtime.

For example, put something like this in a module that will execute when Django initializes (such as models.py):

from easy_thumbnails.alias import aliases
if not aliases.get('badge'):
    aliases.set('badge', {'size': (150, 80), 'crop': True})

Templates

To make the easy-thumbnail template library available for use in your template, use:

{% load thumbnail %}

thumbnail_url filter

easy_thumbnails.templatetags.thumbnail.thumbnail_url(source, alias)

Return the thumbnail url for a source file using an aliased set of thumbnail options.

If no matching alias is found, returns an empty string.

Example usage:

<img src="{{ person.photo|thumbnail_url:'small' }}" alt="">

{% thumbnail %} tag

If you want to create a thumbnail without providing an alias, use this tag to generate the thumbnail by specifying all of the required options (or with an alias name, to override/supplement the default alias options with dynamic content).

easy_thumbnails.templatetags.thumbnail.thumbnail(parser, token)

Creates a thumbnail of an ImageField.

Basic tag Syntax:

{% thumbnail [source] [size] [options] %}

source must be a File object, usually an Image/FileField of a model instance.

size can either be:

  • the name of an alias
  • the size in the format [width]x[height] (for example, {% thumbnail person.photo 100x50 %}) or
  • a variable containing a valid size (i.e. either a string in the [width]x[height] format or a tuple containing two integers): {% thumbnail person.photo size_var %}.

options are a space separated list of options which are used when processing the image to a thumbnail such as sharpen, crop and quality=90.

If size is specified as an alias name, options are used to override and/or supplement the options defined in that alias.

The thumbnail tag can also place a ThumbnailFile object in the context, providing access to the properties of the thumbnail such as the height and width:

{% thumbnail [source] [size] [options] as [variable] %}

When as [variable] is used, the tag doesn’t output anything. Instead, use the variable like a standard ImageFieldFile object:

{% thumbnail obj.picture 200x200 upscale as thumb %}
<img src="{{ thumb.url }}"
     width="{{ thumb.width }}"
     height="{{ thumb.height }}" />

Debugging

By default, if there is an error creating the thumbnail or resolving the image variable then the thumbnail tag will just return an empty string (and if there was a context variable to be set then it will also be set to an empty string).

For example, you will not see an error if the thumbnail could not be written to directory because of permissions error. To display those errors rather than failing silently, set THUMBNAIL_DEBUG = True in your Django project’s settings module.

For a full list of options, read the Image Processors reference documentation.

Fallback images

If you need to support fallback or default images at template level you can use:

{% thumbnail object.image|default:'img/default_image.png' 50x50 %}

Where the image string is relative to your default storage (usually the MEDIA_ROOT setting).

Other thumbnailer filters

There are two filters that you can use if you want to get direct access to a thumbnailer in your template. This can be useful when dealing with aliased thumbnails.

easy_thumbnails.templatetags.thumbnail.thumbnailer(obj, relative_name=None)

Creates a thumbnailer from an object (usually a FileField).

Example usage:

{% with photo=person.photo|thumbnailer %}
{% if photo %}
    <a href="{{ photo.large.url }}">
        {{ photo.square.tag }}
    </a>
{% else %}
    <img src="{% static 'template/fallback.png' %}" alt="" />
{% endif %}
{% endwith %}

If you know what you’re doing, you can also pass the relative name:

{% with photo=storage|thumbnailer:'some/file.jpg' %}...
easy_thumbnails.templatetags.thumbnail.thumbnailer_passive(obj)

Creates a thumbnailer from an object (usually a FileFile) that won’t generate new thumbnails.

This is useful if you are using another process to generate the thumbnails rather than having them generated on the fly if they are missing.

Example usage:

{% with avatar=person.avatar|thumbnailer_passive %}
    {% with avatar_thumb=avatar.small %}
        {% if avatar_thumb %}
            <img src="{{ avatar_thumb.url }}" alt="" />
        {% else %}
            <img src="{% static 'img/default-avatar-small.png' %}"
                alt="" />
        {% endif %}
    {% endwith %}
{% endwith %}

Finally, if you want to have an image inserted inline into the template as a data URI, use this filter:

easy_thumbnails.templatetags.thumbnail.data_uri(thumbnail)

This filter will return the base64 encoded data URI for a given thumbnail object.

Example usage:

{% thumbnail sample_image 25x25 crop as thumb %}
<img src="{{ thumb|data_uri }}">

will for instance be rendered as:

Models

You can use the ThumbnailerField or ThumbnailerImageField fields (based on FileField and ImageField, respectively) for easier access to retrieve (or generate) thumbnail images, use different storages and resize source images before saving.

class easy_thumbnails.fields.ThumbnailerField(*args, **kwargs)

A file field which provides easier access for retrieving (and generating) thumbnails.

To use a different file storage for thumbnails, provide the thumbnail_storage keyword argument.

class easy_thumbnails.fields.ThumbnailerImageField(*args, **kwargs)

An image field which provides easier access for retrieving (and generating) thumbnails.

To use a different file storage for thumbnails, provide the thumbnail_storage keyword argument.

To thumbnail the original source image before saving, provide the resize_source keyword argument, passing it a usual thumbnail option dictionary. For example:

ThumbnailerImageField(
    ..., resize_source=dict(size=(100, 100), sharpen=True))

Forms

class easy_thumbnails.widgets.ImageClearableFileInput(thumbnail_options=None, attrs=None)

Use this widget to show a thumbnail of the image next to the image file.

If using the admin and ThumbnailerField, you can use this widget automatically with the following code:

class MyModelAdmin(admin.ModelAdmin):
    formfield_overrides = {
        ThumbnailerField: {'widget': ImageClearableFileInput},
    }
__init__(thumbnail_options=None, attrs=None)

Set up the thumbnail options for this widget.

Parameters:thumbnail_options – options used to generate the thumbnail. If no size is given, it’ll be (80, 80). If not provided at all, default options will be used from the THUMBNAIL_WIDGET_OPTIONS setting.

Python

Easy thumbnails uses a Django File-like object called a Thumbnailer to generate thumbnail images from the source file which it references.

get_thumbnailer

The easy way to create a Thumbnailer instance is to use the following utility function:

easy_thumbnails.files.get_thumbnailer(obj, relative_name=None)

Get a Thumbnailer for a source file.

The obj argument is usually either one of the following:

  • FieldFile instance (i.e. a model instance file/image field property).
  • A string, which will be used as the relative name (the source will be set to the default storage).
  • Storage instance - the relative_name argument must also be provided.

Or it could be:

  • A file-like instance - the relative_name argument must also be provided.

    In this case, the thumbnailer won’t use or create a cached reference to the thumbnail (i.e. a new thumbnail will be created for every Thumbnailer.get_thumbnail() call).

If obj is a Thumbnailer instance, it will just be returned. If it’s an object with an easy_thumbnails_thumbnailer then the attribute is simply returned under the assumption it is a Thumbnailer instance)

Once you have an instance, you can use the Thumbnailer.get_thumbnail() method to retrieve a thumbnail, which will (by default) generate it if it doesn’t exist (or if the source image has been modified since it was created).

For example, assuming an aardvark.jpg image exists in the default storage:

from easy_thumbnails.files import get_thumbnailer

thumbnailer = get_thumbnailer('animals/aardvark.jpg')

thumbnail_options = {'crop': True}
for size in (50, 100, 250):
    thumbnail_options.update({'size': (size, size)})
    thumbnailer.get_thumbnail(thumbnail_options)

# or to get a thumbnail by alias
thumbnailer['large']

Non-Django file objects

If you need to process a standard file-like object, use get_thumbnailer() and provide a relative_name like this:

picture = open('/home/zookeeper/pictures/my_anteater.jpg')
thumbnailer = get_thumbnailer(picture, relative_name='animals/anteater.jpg')
thumb = thumbnailer.get_thumbnail({'size': (100, 100)})

If you don’t even need to save the thumbnail to storage because you are planning on using it in some more direct way, you can use the Thumbnailer.generate_thumbnail() method.

Thumbnails generated in this manor don’t use any cache reference, i.e. every call to Thumbnailer.get_thumbnail() will generate a fresh thumbnail image.