Thumbnails for Django
|jazzband-badge| |pypi| |python-badge| |django-badge| |docs| |gh-actions| |codecov|
Thumbnails for Django.
Django supported versions policy_Pillow, ImageMagick, PIL, Wand, pgmagick, and vipsthumbnailRead more in the documentation (latest version) <https://sorl-thumbnail.readthedocs.io/>_
|jazzband|
This is a Jazzband <https://jazzband.co>_ project. By contributing you agree to
abide by the Contributor Code of Conduct <https://jazzband.co/about/conduct>_
and follow the guidelines <https://jazzband.co/about/guidelines>_.
Feel free to create a new Pull request if you want to propose a new feature. If you need development support or want to discuss with other developers join us in the channel #sorl-thumbnail at freenode.net or Gitter.
For releases updates and more in deep development discussion use our mailing list in Google Groups.
IRC Channel: irc://irc.freenode.net/#sorl-thumbnail
Mailing List: sorl-thumbnail@googlegroups.com https://groups.google.com/d/forum/sorl-thumbnail
The tests should run with tox and pytest. Running tox will run all tests for all environments.
However, it is possible to run a certain environment with tox -e <env>, a list of all environments
can be found with tox -l. These tests require the dependencies of the different engines defined in
the documentation. It is possible to install these dependencies into a vagrant image with the
Vagrantfile in the repo.
If you need help using sorl-thumbnail browse https://stackoverflow.com/questions/tagged/sorl-thumbnail
and posts your questions with the sorl-thumbnail tag.
Getting the code for the latest stable release use 'pip'. ::
$ pip install sorl-thumbnail
Then register 'sorl.thumbnail', in the 'INSTALLED_APPS' section of your project's settings. ::
INSTALLED_APPS = [
'django.contrib.auth',
'django.contrib.admin',
'django.contrib.sites',
'django.contrib.comments',
'django.contrib.sessions',
'django.contrib.messages',
'django.contrib.contenttypes',
'sorl.thumbnail',
]
All of the examples assume that you first load the thumbnail template tag in your template.::
{% load thumbnail %}
A simple usage. ::
{% thumbnail item.image "100x100" crop="center" as im %}
<img src="{{ im.url }}" width="{{ im.width }}" height="{{ im.height }}">
{% endthumbnail %}
See more examples in the section Template examples_ in the Documentation
Using the ImageField that automatically deletes references to itself in the key value store and its thumbnail references and the thumbnail files when deleted. Please note that this is only compatible with django 1.2.5 or less.::
from django.db import models
from sorl.thumbnail import ImageField
class Item(models.Model):
image = ImageField(upload_to='whatever')
See more examples in the section Model examples_ in the Documentation
You can use the 'get_thumbnail'::
from sorl.thumbnail import get_thumbnail
from sorl.thumbnail import delete
im = get_thumbnail(my_file, '100x100', crop='center', quality=99)
delete(my_file)
See more examples in the section Low level API examples_ in the Documentation
Alternatively, you load the templatetags by {% load sorl_thumbnail %}
instead of traditional {% load thumbnail %}. It's especially useful in
projects that do make use of multiple thumbnailer libraries that use the
same name (thumbnail) for the templatetag module::
{% load sorl_thumbnail %}
{% thumbnail item.image "100x100" crop="center" as im %}
<img src="{{ im.url }}" width="{{ im.width }}" height="{{ im.height }}">
{% endthumbnail %}
Possible related to the implementation of your Amazon S3 Backend, see the issue #351_
due the storage backend reviews if there is an existing thumbnail when tries to
generate the thumbnail that makes an extensive use of the S3 API
A fast workaround if you are not willing to tweak your storage backend is to set::
THUMBNAIL_FORCE_OVERWRITE = True
So it will avoid to overly query the S3 API.
.. |gh-actions| image:: https://github.com/jazzband/sorl-thumbnail/workflows/Test/badge.svg :target: https://github.com/jazzband/sorl-thumbnail/actions .. |docs| image:: https://readthedocs.org/projects/pip/badge/?version=latest :alt: Documentation for latest version :target: https://sorl-thumbnail.readthedocs.io/en/latest/ .. |pypi| image:: https://img.shields.io/pypi/v/sorl-thumbnail.svg :target: https://pypi.python.org/pypi/sorl-thumbnail :alt: sorl-thumbnail on PyPI .. |python-badge| image:: https://img.shields.io/pypi/pyversions/sorl-thumbnail.svg :target: https://pypi.python.org/pypi/sorl-thumbnail :alt: Supported Python versions .. |django-badge| image:: https://img.shields.io/pypi/djversions/sorl-thumbnail.svg :target: https://pypi.python.org/pypi/sorl-thumbnail :alt: Supported Python versions .. |codecov| image:: https://codecov.io/gh/jazzband/sorl-thumbnail/branch/master/graph/badge.svg :target: https://codecov.io/gh/jazzband/sorl-thumbnail :alt: Coverage .. |jazzband-badge| image:: https://jazzband.co/static/img/badge.svg :target: https://jazzband.co/ :alt: Jazzband .. |jazzband| image:: https://jazzband.co/static/img/jazzband.svg :target: https://jazzband.co/ :alt: Jazzband
.. _Pillow: https://pillow.readthedocs.io/
.. _ImageMagick: https://imagemagick.org/
.. _PIL: https://python-pillow.org/
.. _Wand: https://docs.wand-py.org/
.. _pgmagick: https://pgmagick.readthedocs.io/
.. _vipsthumbnail: https://www.libvips.org/API/current/Using-vipsthumbnail.html
.. _Template examples: https://sorl-thumbnail.readthedocs.io/en/latest/examples.html#template-examples
.. _Model examples: https://sorl-thumbnail.readthedocs.io/en/latest/examples.html#model-examples
.. _Low level API examples: https://sorl-thumbnail.readthedocs.io/en/latest/examples.html#low-level-api-examples
.. _issue #351: https://github.com/jazzband/sorl-thumbnail/issues/351
.. _Django supported versions policy: https://www.djangoproject.com/download/#supported-versions