Install & Compatibility
Where this runs
tested against v13.0.0 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslpy 3.10–3.940 runs
installs and imports cleanly · install 0.0s · import 0.574s · 91.2MB
glibcpy 3.10–3.940 runs
installs and imports cleanly · install 3.3s · import 0.538s · 92MB
91MB installed
● package 91MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
ImageField
✓ from sorl.thumbnail import ImageField
get_thumbnail
✓ from sorl.thumbnail import get_thumbnail
{% load thumbnail %}
✓ {% load thumbnail %}
✗ {% load sorl.thumbnail %}
The template tag library is 'thumbnail', not 'sorl.thumbnail'. If clashing with another 'thumbnail' tag, use `{% load sorl_thumbnail %}` (introduced in v12.0) or Django's `libraries` option to alias it.
To get started, install `sorl-thumbnail` and `Pillow`, then add `sorl.thumbnail` to your Django `INSTALLED_APPS`. If using the cached database key-value store (the default), run `python manage.py migrate`. You can then use the `ImageField` in your models or the `{% thumbnail %}` template tag to generate and display thumbnails. Remember to configure `MEDIA_ROOT` and potentially `STORAGES` in your Django settings. This quickstart includes a basic Django setup for a runnable example.
import os
import django
from django.conf import settings
from django.core.files.uploadedfile import SimpleUploadedFile
from django.db import models
settings.configure(
INSTALLED_APPS=[
'django.contrib.auth',
'django.contrib.contenttypes',
'django.contrib.sessions',
'django.contrib.messages',
'django.contrib.staticfiles',
'sorl.thumbnail',
'myapp'
],
DATABASES={
'default': {
'ENGINE': 'django.db.backends.sqlite3',
'NAME': ':memory:',
}
},
MEDIA_ROOT=os.path.join(os.path.dirname(__file__), 'media'),
STATIC_ROOT=os.path.join(os.path.dirname(__file__), 'static'),
STATIC_URL='/static/',
THUMBNAIL_KEY_PREFIX='sorl-test-',
THUMBNAIL_STORAGE='default',
STORAGES = {
'default': {
'BACKEND': 'django.core.files.storage.FileSystemStorage'
},
'thumbnails': {
'BACKEND': 'django.core.files.storage.FileSystemStorage'
}
},
SECRET_KEY=os.environ.get('DJANGO_SECRET_KEY', 'a-very-secret-key-for-testing'),
TEMPLATES=[
{
'BACKEND': 'django.template.backends.django.DjangoTemplates',
'APP_DIRS': True,
'OPTIONS': {
'context_processors': [
'django.template.context_processors.debug',
'django.template.context_processors.request',
'django.contrib.auth.context_processors.auth',
'django.contrib.messages.context_processors.messages',
],
},
},
],
)
django.setup()
class Item(models.Model):
image = ImageField(upload_to='items')
def __str__(self):
return f"Item {self.pk}"
# --- Example Usage ---
from sorl.thumbnail import get_thumbnail
from django.template import Context, Template
# Create a dummy image file
dummy_image = SimpleUploadedFile("test_image.jpg", b"file_content", content_type="image/jpeg")
# Save an item with the image
item = Item.objects.create(image=dummy_image)
# Generate a thumbnail using the low-level API
thumbnail_obj = get_thumbnail(item.image, '100x100', crop='center', quality=95)
print(f"Generated thumbnail URL: {thumbnail_obj.url}")
# Simulate template rendering (requires a request context usually)
# For a true runnable example without a full Django app, this is tricky.
# This part demonstrates the template tag usage conceptually.
# In a real Django project, you'd put {% load thumbnail %} and the tag in your .html file.
# Example template snippet
template_str = """
{% load thumbnail %}
<img src="{% thumbnail item.image '50x50' crop='center' as im %}{{ im.url }}{% endthumbnail %}">
"""
template = Template(template_str)
context = Context({'item': item})
# This will likely fail without a full Django test setup that handles file storage properly
# print(template.render(context))
# Clean up (optional, for real apps, let Django manage)
item.image.delete(save=False)
item.delete()
Debug
Known issues
breakingIn version 13.0.0, `THUMBNAIL_STORAGE` should now be an alias referring to an entry in Django's `STORAGES` setting, instead of a direct dotted path to a storage class. While the old way is still supported, using aliases is crucial for correct serialization and preserving storage options (like S3 bucket names) when thumbnails are cached and retrieved, especially with cloud backends. Upgrading may orphan existing thumbnail references if not properly handled during migration.fixUpdate your Django `settings.py`. Define your storage backend in `STORAGES` and set `THUMBNAIL_STORAGE` to its alias. Example:
```python
STORAGES = {
"default": {
"BACKEND": "django.core.files.storage.FileSystemStorage",
},
"thumbnails": {
"BACKEND": "storages.backends.s3boto3.S3Boto3Storage",
"OPTIONS": {
"bucket_name": "my-thumbnail-bucket",
},
},
}
THUMBNAIL_STORAGE = 'thumbnails'
``` affects: >=13.0.0
deprecatedThe `THUMBNAIL_KVSTORE` setting is deprecated since version 12.11.0. In future versions, only the Django cache-based store will be used. If you rely on custom KV stores (like DBM or a direct Redis KVStore setup), you should transition to using Django's cache framework.fixEnsure your Django `CACHES` setting is configured correctly and that `sorl-thumbnail` is using the default cached database KV store. If you were using a Redis KVStore, configure Redis as a Django cache backend instead. Example `settings.py`:
```python
CACHES = {
'default': {
'BACKEND': 'django_redis.cache.RedisCache',
'LOCATION': os.environ.get('REDIS_URL', 'redis://127.0.0.1:6379/1'),
}
}
# THUMBNAIL_KVSTORE will implicitly use 'default' cache
``` affects: >=12.11.0
gotchaSorl Thumbnail relies on a Key-Value Store for its operation. The default is a cached database, which requires `python manage.py migrate` to create necessary tables. For better performance, especially in production, a fast cache like Memcached or Redis is highly recommended. Not running migrations or having a slow/unconfigured KV store can lead to performance issues or errors.fixAfter adding `sorl.thumbnail` to `INSTALLED_APPS`, always run `python manage.py migrate`. For production, configure a robust cache in your `settings.py` (e.g., Redis via `django-redis`) and ensure it's properly set up. Install `redis` package for Redis integration.
affects: All versions
gotchaGenerating many thumbnails for the first time on a page can be slow, potentially causing request timeouts on web servers if the timeout is set too low. This is due to the synchronous nature of thumbnail generation on first access.fixIncrease your web server's request timeout (e.g., Gunicorn's `--timeout` setting). For frequently accessed images, consider pre-generating thumbnails using management commands (`thumbnail cleanup --all`) or an asynchronous task queue (like Celery) to avoid on-demand generation during user requests.
affects: All versions
breakingSorl Thumbnail has dropped support for older Python and Django versions incrementally. For instance, Python 3.7 support was removed in 12.10.0, Python 3.8/3.9 in 13.0.0, and Django 3.2, 4.0, 4.1 in 12.11.0. Running with unsupported versions can lead to unexpected errors or vulnerabilities.fixAlways check the `sorl-thumbnail` release notes for compatibility with your Python and Django versions before upgrading or starting a new project. Ensure your environment meets the `requires_python` and Django compatibility of the `sorl-thumbnail` version you are using. For v13.0.0, Python >= 3.10 is required.
affects: <13.0.0 for newer Python/Django, check specific release notes for details.
Upgrade
Version history
13.0.0latest on PyPI · released Jan 22, 2026
Audit
Dependencies
DjangorequiredCore framework integration.
PillowrequiredRequired for image processing and manipulation. Other engines like ImageMagick/GraphicsMagick (with `wand` or `pgmagick`) are also supported but Pillow is the most common.
redisoptionalOptional, but highly recommended for a faster Key-Value Store backend than the default cached database.
django-storagesoptionalOptional, required for integrating with cloud storage services like Amazon S3 or Google Cloud Storage.