Creating thumbnails

thumbnails.get_thumbnail should be used to generate thumbnails from python code. It takes the original image and size is positional arguments and needs to be passed each time the function is called. Other options can be passed as keyword arguments. The available options is listed below:

thumbnails.get_thumbnail(original, size, **options)[source]

Creates or gets an already created thumbnail for the given image with the given size and options.

  • original – File-path, url or base64-encoded string of the image that you want an thumbnail.
  • size – String with the wanted thumbnail size. On the form: 200x200, 200 or x200.
  • crop – Crop settings, should be center, top, right, bottom, left.
  • force – If set to True the thumbnail will be created even if it exists before.
  • quality – Overrides THUMBNAIL_QUALITY, will set the quality used by the backend while saving the thumbnail.
  • scale_up – Overrides THUMBNAIL_SCALE_UP, if set to True the image will be scaled up if necessary.
  • colormode – Overrides THUMBNAIL_COLORMODE, The default colormode for thumbnails. Supports all values supported by pillow. In other engines there is a best effort translation from pillow modes to the modes supported by the current engine.
  • format – Overrides the format the thumbnail will be saved in. This will override both the detected file type as well as the one specified in THUMBNAIL_FALLBACK_FORMAT.

A Thumbnail object

Django specific features



This templatetag is a shortcut for thumbnails.get_thumbnail, thus all arguments and keyword arguments are the same as described in the section above. It is necessary to define the variable name for the thumbnail with an as keyword as shown in the example below.

{% load thumbnails %}

{% get_thumbnail "image.jpg" "400x400" crop="center" as thumbnail %}
<img src="{{ thumbnail.url }}" alt="The thumbnail" style="width: {{ thumbnail.width }} />



Markdown filter that replaces all images with thumbnails.

{% load thumbnails %}

{{ content|markdown_thumbnails }}

HTML filter that replaces all images with thumbnails, the returned string is marked as safe.

{% load thumbnails %}

{{ content|html_thumbnails }}

HTML filter that replaces all images with thumbnails, the returned string is not marked as safe.

{% load thumbnails %}

{{ content|safe_html_thumbnails }}

Creating custom text filters

It is possible to create custom text filters by utilizing the text_filter function described below.

thumbnails.templatetags.thumbnails.text_filter(regex_base, value)[source]

A text-filter helper, used in markdown_thumbnails-filter and html_thumbnails-filter. It can be used to build custom thumbnail text-filters.

  • regex_base – A string with a regex that contains %(captions)s and %(image)s where the caption and image should be.
  • value – String of text in which the source URLs can be found.

A string ready to be put in a template.

Below is the code for the html_thumbnails-filter shown as an example of how to use text_filter.

def html_thumbnails(value):
    return mark_safe(text_filter('<img(?: alt="(%(caption)s)?")? src="(%(image)s)"', value))