sorl-thumbnail
Thumbnails for Django. You write the size in the template, or ask for it in Python, and sorl-thumbnail makes the thumbnail on first use with Pillow, libvips or ImageMagick, saves it on your media storage and remembers it in a key-value store, so later renders cost no image work and no storage request.
Website, with an example gallery for every image engine: https://mariocesar.github.io/sorl-thumbnail/
Documentation: https://sorl-thumbnail.readthedocs.io/
Quick start
Install sorl-thumbnail with Pillow:
pip install "sorl-thumbnail[pil]"
Add 'sorl.thumbnail' to INSTALLED_APPS:
INSTALLED_APPS = [
...
'sorl.thumbnail',
]
and create its table:
python manage.py migrate
Then, in a template:
{% load thumbnail %}
{% thumbnail item.image "100x100" crop="center" as im %}
<img src="{{ im.url }}" width="{{ im.width }}" height="{{ im.height }}">
{% endthumbnail %}
item.image can be an ImageField, a path in your media storage or the URL of an image. The same from Python:
from sorl.thumbnail import get_thumbnail im = get_thumbnail(item.image, '100x100', crop='center', quality=99)
The quickstart walks through this. The documentation covers the template tag and its options, every setting, thumbnails on Amazon S3 and troubleshooting.
Features
Resize to a box, a width or a height. Crop by position, percentage, pixels or a crop box, crop to the busiest part of the image, or cut plain borders first.
JPEG, PNG, GIF, WEBP and AVIF output, with quality, progressive JPEG, grayscale, padding, rounded corners and blur. Animated GIFs stay animated with Pillow and libvips.
Follows the EXIF orientation of photos.
Any Django storage for sources and thumbnails, Amazon S3 included. The key-value store, your database read through your cache or Redis, remembers every thumbnail, so a cached one costs no storage request.
An ImageField that validates uploads, an admin widget with a preview, and placeholder images for developing without the real media.
Alternative resolutions for high-density screens, and the is_portrait and margin filters for layout.
Django 5.2, 6.0 and 6.1, following the Django supported versions policy, on Python 3.10 and later.
Engines
The engine does the resizing. Set it with THUMBNAIL_ENGINE; Pillow is the default.
Pillow, the default: pip install "sorl-thumbnail[pil]".
libvips through pyvips: pip install "sorl-thumbnail[vips]".
ImageMagick, through its convert and identify commands. Also reads PDF pages.
GraphicsMagick, the same engine through gm convert and gm identify.
Wand, a Python binding for ImageMagick: pip install "sorl-thumbnail[wand]".
pgmagick, a Python binding for GraphicsMagick: pip install "sorl-thumbnail[pgmagick]".
Each engine has an example gallery on the website, and the documentation lists which options each one supports.
Using it next to another thumbnail library
Other libraries also register a thumbnail template library. Load sorl-thumbnail’s tags as sorl_thumbnail instead, the tag is the same:
{% load sorl_thumbnail %}
Help
Ask in the Q&A category of GitHub Discussions. Report bugs in the issue tracker.
Contributing
Pull requests are welcome. The contributing guide explains how to run the tests and send a change. Using AI tools is fine if you say so and test the change yourself; pull requests sent by scripts are closed. By contributing you agree to the Code of Conduct. To report a security issue, follow the security policy instead of opening a public issue.
The tests run with tox through uv, one environment per Python, Django and engine:
uvx --with tox-uv tox -l uvx --with tox-uv tox -e py312-django52-pil
The Pillow and libvips environments need nothing else. The others need the engine’s tools, see the requirements, or run them in Docker as the contributing guide shows.
License
BSD 3-Clause, see the LICENSE file.
1 maintainer
Metadata
1 maintainer
Release files for sorl-thumbnail 13.4.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.4.0.tar.gz | 791.4 kB | With provenance | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| sorl_thumbnail-13.4.0-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 838.4 kB
Release files / sorl_thumbnail-13.4.0.tar.gz
| Download URL | sorl_thumbnail-13.4.0.tar.gz |
|---|---|
| Size | 791.4 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
9eafa7be3c6785b06750633a36b20111005b7e3efda735f770e0ee101908ed3b
|
|
BLAKE2b-256 checksum How to use checksums |
e2ebc82291c848d41fef671b754943c00cfba3cd94ad138b22738368a93768d5
|
| 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 25, 2026.
Transparency logRelease files / sorl_thumbnail-13.4.0-py3-none-any.whl
| Download URL | sorl_thumbnail-13.4.0-py3-none-any.whl |
|---|---|
| Size | 47.0 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
375c7c8760424aeec6d8c394d158b2390afd0129c61ad73e90b6766cea88d600
|
|
BLAKE2b-256 checksum How to use checksums |
96f8fb13cef9e0cbff62c0cf037903820a81f38f75b7e7d2333d8124170f6574
|
| 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 25, 2026.
Transparency logSecurity for sorl-thumbnail 13.4.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.4.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 25, 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.
