Skip to main content
Help us improve Python packaging – donate today!

Easy thumbnails for Django

Project Description

Build Status

A powerful, yet easy to implement thumbnailing application for Django 1.4+

Below is a quick summary of usage. For more comprehensive information, view the full documentation online or the peruse the project’s docs directory.


Run pip install easy-thumbnails, or for the in-development version run pip install easy-thumbnails==dev.

Add easy_thumbnails to your INSTALLED_APPS setting:


If you have South installed then run migrate easy_thumbnails, otherwise just run syncdb.

Example usage

Thumbnail options can be predefined in settings.THUMBNAIL_ALIASES or just specified in the template or Python code when run.

Using a predefined alias

Given the following setting:

    '': {
        'avatar': {'size': (50, 50), 'crop': True},


{% load thumbnail %}
<img src="{{|thumbnail_url:'avatar' }}" alt="" />


from easy_thumbnails.files import get_thumbnailer
thumb_url = get_thumbnailer(['avatar'].url

Manually specifying size / options


{% load thumbnail %}
<img src="{% thumbnail 50x50 crop %}" alt="" />


from easy_thumbnails.files import get_thumbnailer
options = {'size': (100, 100), 'crop': True}
thumb_url = get_thumbnailer(


You can use ThumbnailerImageField (or ThumbnailerFileField) for easier access to retrieve or generate thumbnail images.

For example:

from easy_thumbnails.fields import ThumbnailerImageField

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

Accessing the field’s predefined alias in a template:

{% load thumbnail %}
<img src="{{ }}" alt="" />

Accessing the field’s predefined alias in Python code:

thumb_url =['avatar'].url

Thumbnail options


Before scaling the image down to fit within the size bounds, it first cuts the edges of the image to match the requested aspect ratio.

Use crop="smart" to try to keep the most interesting part of the image,

Use crop="0,10" to crop from the left edge and a 10% offset from the top edge. Crop from a single edge by leaving dimension empty (e.g. crop=",0"). Offset from the right / bottom by using negative numbers (e.g., crop=”-0,-10”).

Often used with the upscale option, which will allow enlarging of the image during scaling.


Changes the quality of the output JPEG thumbnail. Defaults to 85.

In Python code, this is given as a separate option to the get_thumbnail method rather than just alter the other

Other options

Valid thumbnail options are determined by the “thumbnail processors” installed.

See the reference documentation for a complete list of options provided by the default thumbnail processors.


2.1 (2014-08-13)

  • Fix Python 3.4 installation issue.
  • Avoid an OverflowError due to invalid EXIF data.
  • Fix bug causing JPEG images to be saved without optimization :(
  • JPEG files can now be saved with progressive encoding. By default, any image with a dimension larger than 100px will be saved progressively. Configured with the THUMBNAILER_PROGRESSIVE setting.

2.0.1 (2014-04-26)

  • Fix packaging issue with old south migrations.

2.0 (2014-04-25)

  • Use Django 1.7 migrations. Thanks Trey Hunner. Note: if using South, read the installation docs for required settings changes.
  • Make ThumbnailerImageField.resize_source reflect change in extension.
  • Add target option to the scale_and_crop processor, allowing for image focal points when cropping (or zooming) an image.
  • Add a THUMBNAIL_NAMER option which takes a function used to customize the thumbnail filename.
  • New subsampling option to reduce color subsampling of JPEG images, providing sharper color borders for a small increase in file size.
  • Reimplementation of the thumbnail_cleanup command. Thanks Jørgen Abrahamsen
  • More efficient thumbnail default storage. Thanks Sandip Agarwal.

1.5 (2014-03-05)

  • Better support for multiple source generators.
  • Update method used to check for modification dates of source and thumbnail images. Thanks Ben Roberts.
  • Better thumbnail_high_resolution handling, including the ability to switch on and off explicitly with a HIGH_RESOLUTION thumbnail option.
  • Added configuration option to specify the infix used for high resolution image handling.
  • Optional postprocessor for image optimization. Thanks Jacob Rief!
  • More remote storages optimization
  • Thumbnail dimensions can now optionally be cached. Thanks David Novakovic.
  • New zoom option to generate a thumbnail of a source image with a percentage clipped off each side.
  • New background source processor that can add a border color to ensure scaled images fit within the exact dimensions given.

1.4 (2013-09-23)

  • Considerable speed up for remote storages by reducing queries. Brent O’Connor spent a lot of time debugging this, so thank you epicserve!
  • Allow the {% thumbnail %} tag to also accept aliases. Thanks Simon Meers!
  • Make replace_alpha actually work correctly.
  • Fixes exception being raised when image exists in cache but is doesn’t actually exist in the storage.
  • Fixes Python 2.5 compatibility.

1.3 (2013-06-17)

  • Some more Django 1.5 fixes.
  • Fix an issue with Thumbnail.url not working correctly.
  • Add the ability to generate retina quality thumbnails in addition to the standard ones (off by default).

1.2 (2013-01-23)

  • Django 1.5 compatibility.
  • Fixed a problem with the ImageClearableFileInput widget.

1.1 (2012-08-29)

  • Added a way to avoid generating thumbnails if they don’t exist already (with a signal to deal with them elsewhere).
  • Added a thumbnailer_passive filter to allow templates to use the non-generating thumbnails functionality when dealing with aliases.

1.0.3 (2012-05-30)

  • Changed the exception to catch from 1.0.2 to IOError.

1.0.2 (2012-05-29)

  • Catch an OSError exception when trying to get the EXIF data of a touchy image.

1.0.1 (2012-05-23)

  • Fix a Django 1.2 backwards incompatibility in easy_thumbnails.conf
  • Introduced a thumbnail_created signal.

1.0 (2012-05-07)

  • Introduction of aliased thumbnails.
  • Start of sane versioning numbers.

Release history Release notifications

History Node


History Node


History Node


History Node


History Node


History Node


This version
History Node


History Node


History Node


History Node


History Node


History Node


History Node


History Node


History Node


History Node


History Node


History Node


History Node


History Node


History Node


History Node


History Node


History Node


History Node


History Node


History Node


History Node


History Node


History Node


History Node


History Node


History Node


History Node


History Node


History Node


History Node


History Node


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Filename, size & hash SHA256 hash help File type Python version Upload date
easy-thumbnails-2.1.tar.gz (71.2 kB) Copy SHA256 hash SHA256 Source None Aug 13, 2014

Supported by

Elastic Elastic Search Pingdom Pingdom Monitoring Google Google BigQuery Sentry Sentry Error logging CloudAMQP CloudAMQP RabbitMQ AWS AWS Cloud computing Fastly Fastly CDN DigiCert DigiCert EV certificate StatusPage StatusPage Status page