sorl-thumbnail /

Filename Size Date modified Message
0 B
5.4 KB
2.6 KB
866 B
53 B
6.1 KB
4.7 KB

The ``sorl.thumbnail`` package, provides a way of thumbnailing images.

It requires the Python Imaging Library (PIL_).

.. _PIL:

{% thumbnail %} template tag

The usual way to use thumbnails with this package is to use the
``{% thumbnail %}`` template tag.

To use this tag, add ``'sorl.thumbnail'`` to your ``INSTALLED_APPS`` setting.
Once you've done that, use ``{% load thumbnail %}`` in a template to give your
template access to the tag.

Basic usage

The thumbnail tag creates the thumbnail if it didn't exist (or if the source
image was modified more recently than the existing thumbnail) and then returns
the absolute url of the thumbnail (``MEDIA_URL`` + relative thumbnail
url). The basic usage is::

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

``source-filename`` must be an existing image, including the path relative to

``size`` must be with the size in the format
``[width]x[height]`` (for example, ``250x250``). Then other options

``options`` are optional (obviously) and should be comma separated (without a space
between them - for example, ``crop,bw,quality=95``). Valid options are:

      Alter the quality of the JPEG thumbnail (the default is 85).

      Crop the source image height or width to exactly match the requested
      thumbnail size (the default is to proportionally resize the source image
      to fit within the requested thumbnail size).

      Remove any unnecessary whitespace from the edges of the source image.
      This occurs before the crop or propotional resize.

      Make the thumbnail grayscale (not really just black & white).

      Allow upscaling of the source image during scaling.

      Sharpen the thumbnail image (using the PIL sharpen filter)

      Add detail to the image, like a mild ``sharpen`` (using the PIL detail

An example of basic usage::

    <img src="{% thumbnail 80x80 crop,upscale %}" />

Advanced usage

The thumbnail tag can also place a ``DjangoThumbnail`` object on the context,
providing access to the properties of the thumbnail such as the height and

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

When ``as [variable]`` is used, the tag does not return the absolute url of the
thumbnail. The variable (containing the ``DjangoThumbnail`` object) has the
following useful properties:

      The absolute url of the thumbnail (the ``__unicode__`` method of this
      object also returns the absolute url, so you can also just do
      ``{{ thumbnail_variable }}``).

    ``width`` and ``height``
      The width/height of the thumbnail image.

      The file size (as an integer in bytes) of the thumbnail image.

    ``source_width`` and ``source_height``
      The width/height of the source image.

      The file size (as an integer in bytes) of the source image.

An example of advanced usage::

    {% thumbnail 250x250 bw,autocrop as thumb %}
    <img src="{{ thumb }}" width="{{ thumb.width }}" height="{{ thumb.height }}" />

Debugging the thumbnail tag

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

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, add a ``THUMBNAIL_DEBUG``
property to your settings module and set it to ``True``::


Thumbnail filenames

The thumbnail filename is generated from the source filename, the target size,
any options provided and the quality.

For example, ``{% thumbnail "1.jpg" 80x80 crop,bw %}`` will save the
thumbnail image as::

    MEDIA_ROOT + '1_jpg_80x80_crop_bw_q85.jpg'

By default, thumbnails are saved in the same directory as the source image.
You can override this behaviour by adding one or more of the following
properties to your settings module:

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

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

      Prepend thumnail filenames with the specified prefix.

For example, if the tag was ``{% thumbnail "photos/1.jpg" 150x150 %}`` then
``THUMBNAIL_BASEDIR = 'thumbs'`` would save the thumbnail as::

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

or ``THUMBNAIL_SUBDIR = '_thumbs'`` would save the thumbnail as::

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

or ``THUMBNAIL_PREFIX = '__'`` would save the thumbnail as::

    MEDIA_ROOT + '/photos/__1_jpg_150x150_q85.jpg'

Changing the default JPEG quality

If you would rather your thumbnail images have a different default JPEG
quality than 85, add a ``THUMBNAIL_QUALITY`` property to your settings module.
For example::


This will only affect images which have not be explicitly given a quality

Advanced usage

Some helpful methods are provided in the ``sorl.thumbnail.utils`` module. One
example of using these could be to clean up any thumbnails belonging solely to
a model in its ``delete()`` method.

Use the ``DjangoThumbnail`` class in ``sorl.thumbnail.main`` if you want
behaviour similar to the ``{% thumbnail %}`` tag (i.e. using the ``MEDIA_ROOT``
and ``MEDIA_URL``) in your Python code. If you want to use a different file
naming method, just subclass and override the ``_get_relative_thumbnail``

Use the ``Thumbnail`` class in ``sorl.thumbnail.base`` for more low-level
creation of thumbnails. This class doesn't have any Django-specific ties.