Settings

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.

THUMBNAIL_ALIASES = None: A dictionary of predefined alias options for different targets. See the usage documentation for details.

THUMBNAIL_BASEDIR = ''

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_q76.jpg'

THUMBNAIL_CACHE_DIMENSIONS = False

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.

THUMBNAIL_CHECK_CACHE_MISS = False

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.

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

THUMBNAIL_DEFAULT_OPTIONS = None

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

THUMBNAIL_DEFAULT_OPTIONS = {'bw': True}

THUMBNAIL_DEFAULT_STORAGE = 'easy_thumbnails.storage.ThumbnailFileSystemStorage': (DEPRECATED) The default Django storage for saving generated thumbnails.

THUMBNAIL_DEFAULT_STORAGE_ALIAS = 'easy_thumbnails': Django 4.2+: The default Django storage name for saving generated thumbnails.

THUMBNAIL_EXTENSION = 'jpg'

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

The default quality depends on this format, see THUMBNAIL_IMAGE_SAVE_OPTIONS.

THUMBNAIL_HASHER = 'easy_thumbnails.hashers.default'

Dotted path to the function that generates the thumb_hash stored on the Source record when the first thumbnail of a source image is generated.

The function is called with the (PIL) source image and returns a short string, or None if no hash can be generated. Set to None to disable.

The default, easy_thumbnails.hashers.default, generates a ThumbHash (base64 encoded) and requires the thumbhash extra. Without it no hash is stored.

THUMBNAIL_IMAGE_SAVE_OPTIONS = {'AVIF': {'quality': 61}, 'JPEG': {'quality': 76}, 'WEBP': {'quality': 80}}

Image.save parameters per Pillow format name ('JPEG', 'WEBP', 'AVIF', …), for example {'WEBP': {'method': 6}} or, for lossless WebP, {'WEBP': {'lossless': True}}.

The quality entry is the default quality for thumbnails saved in that format, on a scale from 1 (worst) to 100 (best). The defaults give a similar perceived quality across formats for general web content (the same values as Wagtail, see its image quality documentation). For example, for small thumbnails:

THUMBNAIL_IMAGE_SAVE_OPTIONS = {
    'JPEG': {'quality': 65},
    'WEBP': {'quality': 70},
    'AVIF': {'quality': 54},
}

A quality in THUMBNAIL_DEFAULT_OPTIONS, a thumbnail alias or the thumbnail options takes precedence (in increasing order). The quality is part of the thumbnail file name (unless the alias or alias_or_size namer is used), so changing it regenerates the thumbnails.

Setting this replaces the whole dictionary, so include every format you want a default quality for. Formats without a quality entry are saved with Pillow’s default quality.

The default quality is the one of the format the thumbnail is saved in: the format option, a preserved source extension, or THUMBNAIL_TRANSPARENCY_EXTENSION / THUMBNAIL_EXTENSION depending on whether the thumbnail is transparent. See WebP support for details.

THUMBNAIL_MEDIA_ROOT = ''

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.

THUMBNAIL_MEDIA_URL = ''

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.

Five namers are included in easy_thumbnails:

easy_thumbnails.namers.default: Descriptive filename containing the source and options like source.jpg.100x100_q80_crop_upscale.jpg.
easy_thumbnails.namers.hashed: Short hashed filename like 1xedFtqllFo9.jpg.
easy_thumbnails.namers.alias: Filename based on THUMBNAIL_ALIASES dictionary key like source.jpg.medium_large.jpg.
easy_thumbnails.namers.alias_or_size: Like alias, but falls back to the size if there is no alias, like source.medium_large.jpg or source.800x600.jpg.
easy_thumbnails.namers.source_hashed: Filename with source hashed, size, then options hashed like 1xedFtqllFo9_100x100_QHCa6G1l.jpg.

To write your own namer, see Namers.

THUMBNAIL_PREFIX = ''

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_q76.jpg'

THUMBNAIL_PRESERVE_EXTENSIONS = None

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:

THUMBNAIL_PRESERVE_EXTENSIONS = ['png']

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:

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

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.

THUMBNAIL_PROGRESSIVE = 100

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.

THUMBNAIL_SOURCE_GENERATORS = ('easy_thumbnails.source_generators.pil_image', 'easy_thumbnails.source_generators.vil_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.

THUMBNAIL_SUBDIR = ''

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_q76.jpg'

THUMBNAIL_TRANSPARENCY_EXTENSION = 'png': 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.