Thumbnails for Django.
Features at a glance
Support for Django 5.2, 6.0, and 6.1 following the Django supported versions policy
Storage support
Pluggable Engine support for Pillow, ImageMagick, PIL, Wand, pgmagick, and vipsthumbnail
Pluggable Key Value Store support (cached db, redis, and dynamodb by AWS)
Pluggable Backend support
Admin integration with possibility to delete
Dummy generation (placeholders)
Flexible, simple syntax, generates no html
CSS style cropping options
Back smart cropping, and remove borders from the images when cropping
Margin calculation for vertical positioning
Alternative resolutions versions of a thumbnail
Read more in the documentation (latest version)
Developers
By contributing you agree to abide by the Code of Conduct. To report a security issue, follow the security policy instead of opening a public issue.
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 GitHub Discussions.
Tests
The tests run with tox, which uses uv to create its environments. With uv installed, uvx –with tox-uv tox will run all tests for all environments. However, it is possible to run a certain environment with uvx –with tox-uv tox -e <env>, a list of all environments can be found with uvx –with tox-uv tox -l. These tests require the dependencies of the different engines defined in the documentation. The easiest way to run tests is using Docker - see the contributing documentation for detailed instructions on running tests locally with Docker.
User Support
If you need help using sorl-thumbnail ask in the Q&A category of GitHub Discussions.
How to Use
Get the code
Getting the code for the latest stable release use ‘pip’.
$ pip install sorl-thumbnail
Install in your project
Then register ‘sorl.thumbnail’, in the ‘INSTALLED_APPS’ section of your project’s settings.
INSTALLED_APPS = [
'django.contrib.admin',
'django.contrib.auth',
'django.contrib.contenttypes',
'django.contrib.sessions',
'django.contrib.messages',
'django.contrib.staticfiles',
'sorl.thumbnail',
]
Templates Usage
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
Model Usage
You can use sorl.thumbnail.ImageField in your models:
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
Low level API
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
Using in combination with other thumbnailers
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 %}
Frequently asked questions
Is it slow on Amazon S3?
Once a thumbnail is in the key-value store, rendering it makes no request to the storage at all. A slow page means thumbnails are being generated, or the key-value store was cleared or lost. Generating a thumbnail reads the source once and writes the result once, which is as little as it can be.
Older versions of this FAQ recommended THUMBNAIL_FORCE_OVERWRITE = True. That advice dates from boto 2. With boto3 it makes things worse: on a key-value store miss it regenerates the thumbnail from the full-size source instead of making one HEAD request for the file that is already there. See THUMBNAIL_FORCE_OVERWRITE before enabling it.
1 maintainer
Metadata
1 maintainer
Release files for sorl-thumbnail 13.3.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | |
|---|---|---|---|---|
| sorl_thumbnail-13.3.0.tar.gz | 689.9 kB | With provenance | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| sorl_thumbnail-13.3.0-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 734.7 kB
Release files / sorl_thumbnail-13.3.0.tar.gz
| Download URL | sorl_thumbnail-13.3.0.tar.gz |
|---|---|
| Size | 689.9 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
0910f1a4a48d046b202b8ae1767397ecea6640c8c16bdf7dc7e9d007d2ea2fa2
|
|
BLAKE2b-256 checksum How to use checksums |
dfcbd8e07e92bbae0d36b337f68239a7614ee2bb20142ab1738ee0dc054db641
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Oct 24, 2026.
Transparency logRelease files / sorl_thumbnail-13.3.0-py3-none-any.whl
| Download URL | sorl_thumbnail-13.3.0-py3-none-any.whl |
|---|---|
| Size | 44.8 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
36ebd050c8f6a4ee2afb61e76bf4a1a5c2c6d9a54e3f4ebb66972520c4531120
|
|
BLAKE2b-256 checksum How to use checksums |
3e7ae3380cdc35493b9021ca67cab10c284f9a7250488bd1caa93f865af7ec95
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Oct 24, 2026.
Transparency logSecurity for sorl-thumbnail 13.3.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
Full provenance
All 2 files in this release have been uploaded with provenance metadata.
Attestation for sorl_thumbnail-13.3.0.tar.gz
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Oct 24, 2026.
Transparency logA note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.
