class easy_thumbnails.conf.Settings

These default settings for easy-thumbnails can be specified in your Django project’s settings module to alter the behaviour of easy-thumbnails.


A dictionary of predefined alias options for different targets. See the usage documentation for details.


Save thumbnail images to a directory directly off MEDIA_ROOT, still keeping the relative directory structure of the source image.

For example, using the {% thumbnail "photos/1.jpg" 150x150 %} tag with a THUMBNAIL_BASEDIR of 'thumbs' would result in the following thumbnail filename:

MEDIA_ROOT + 'thumbs/photos/1_jpg_150x150_q85.jpg'

Save thumbnail dimensions to the database.

When using remote storage backends it can be a slow process to get image dimensions for a thumbnailed file. This option will store them in the database to be recalled quickly when required. Note: the old method still works as a fall back.


If this boolean setting is set to True, and a thumbnail cannot be found in the database tables, we ask the storage if it has the thumbnail. If it does we add the row in the database, and we don’t need to generate the thumbnail.

Switch this to True if your easy_thumbnails_thumbnail table has been wiped but your storage still has the thumbnail files.


If this boolean setting is set to True, display errors creating a thumbnail when using the {% thumbnail %} tag rather than failing silently.


Set this to a dictionary of options to provide as the default for all thumbnail calls. For example, to make all images greyscale:


The default Django storage for saving generated thumbnails.


The type of image to save thumbnails with no transparency layer as.

Note that changing the extension will most likely cause the THUMBNAIL_QUALITY setting to have no effect.


Sets the infix used to distinguish thumbnail images for retina displays.

Thumbnails generated for retina displays are distinguished from the standard resolution counterparts, by adding an infix to the filename just before the dot followed by the extension.

Apple Inc., formerly suggested to use @2x as infix, but later changed their mind and now suggests to use _2x, since this is more portable.


Enables thumbnails for retina displays.

Creates a version of the thumbnails in high resolution that can be used by a javascript layer to display higher quality thumbnails for high DPI displays.

This can be overridden at a per-thumbnail level with the HIGH_RESOLUTION thumbnail option:

opts = {'size': (100, 100), 'crop': True, HIGH_RESOLUTION: False}
only_basic = get_thumbnailer(obj.image).get_thumbnail(opts)

In a template tag, use a value of 0 to force the disabling of a high resolution version or just the option name to enable it:

{% thumbnail obj.image 50x50 crop HIGH_RESOLUTION=0 %}  {# no hires #}
{% thumbnail obj.image 50x50 crop HIGH_RESOLUTION %}  {# force hires #}

Used by easy-thumbnail’s default storage to locate where thumbnails are stored on the file system.

If not provided, Django’s standard MEDIA_ROOT setting is used.


Used by easy-thumbnail’s default storage to build the absolute URL for a generated thumbnail.

If not provided, Django’s standard MEDIA_URL setting is used.

THUMBNAIL_NAMER = 'easy_thumbnails.namers.default'

The function used to generate the filename for thumbnail images.

Four namers are included in easy_thumbnails:

Descriptive filename containing the source and options like source.jpg.100x100_q80_crop_upscale.jpg.
Short hashed filename like 1xedFtqllFo9.jpg.
Filename based on THUMBNAIL_ALIASES dictionary key like source.jpg.medium_large.jpg.
Filename with source hashed, size, then options hashed like 1xedFtqllFo9_100x100_QHCa6G1l.jpg.

To write a custom namer, always catch all other keyword arguments arguments (with **kwargs). You have access to the following arguments: thumbnailer, source_filename, thumbnail_extension (does not include the '.'), thumbnail_options, prepared_options.

The thumbnail_options are a copy of the options dictionary used to build the thumbnail, prepared_options is a list of options prepared as text, and excluding options that shouldn’t be included in the filename.


Prepend thumbnail filenames with the specified prefix.

For example, using the {% thumbnail "photos/1.jpg" 150x150 %} tag with a THUMBNAIL_PREFIX of 'thumbs_' would result in the following thumbnail filename:

MEDIA_ROOT + 'photos/thumbs_1_jpg_150x150_q85.jpg'

To preserve specific extensions, for instance if you always want to create lossless PNG thumbnails from PNG sources, you can specify these extensions using this setting, for example:


All extensions should be lowercase.

Instead of a tuple, you can also set this to True in order to always preserve the original extension.

THUMBNAIL_PROCESSORS = ('easy_thumbnails.processors.colorspace', 'easy_thumbnails.processors.autocrop', 'easy_thumbnails.processors.scale_and_crop', 'easy_thumbnails.processors.filters', 'easy_thumbnails.processors.background')

Defaults to:


The Image Processors through which the source image is run when you create a thumbnail.

The order of the processors is the order in which they are sequentially called to process the image.


Use progressive JPGs for thumbnails where either dimension is at least this many pixels.

For example, a 90x90 image will be saved as a baseline JPG while a 728x90 image will be saved as a progressive JPG.

Set to False to never use progressive encoding.


The default quality level for JPG images on a scale from 1 (worst) to 95 (best). Technically, values up to 100 are allowed, but this is not recommended.

THUMBNAIL_SOURCE_GENERATORS = ('easy_thumbnails.source_generators.pil_image',)

The Source Generators through which the base image is created from the source file.

The order of the processors is the order in which they are sequentially tried.


Save thumbnail images to a sub-directory relative to the source image.

For example, using the {% thumbnail "photos/1.jpg" 150x150 %} tag with a THUMBNAIL_SUBDIR of 'thumbs' would result in the following thumbnail filename:

MEDIA_ROOT + 'photos/thumbs/1_jpg_150x150_q85.jpg'

The type of image to save thumbnails with a transparency layer (e.g. GIFs or transparent PNGs).

THUMBNAIL_WIDGET_OPTIONS = {'size': (80, 80)}

Default options for the easy_thumbnails.widgets.ImageClearableFileInput widget.