Django Advance Thumbnail

A Django app that automates thumbnail creation for image fields. It generates, updates, and deletes thumbnails based on the source image with support for custom sizes and resize methods.

Features

• Automatic thumbnail generation on model save
• Thread-safe for multi-threaded/parallel web servers (gunicorn, uwsgi, etc.)
• Multiple resize methods: fit (maintain aspect ratio) or fill (exact dimensions)
• Smart regeneration - only regenerates when source image or settings change
• Management commands for bulk operations
• Full Django migrations support

Installation

pip install django-advance-thumbnail

Add to INSTALLED_APPS:

INSTALLED_APPS = [
    # ...
    'django_advance_thumbnail',
]

Quick Start

from django.db import models
from django_advance_thumbnail import AdvanceThumbnailField

class Product(models.Model):
    image = models.ImageField(upload_to='products/')
    thumbnail = AdvanceThumbnailField(
        source_field='image',
        upload_to='thumbnails/',
        size=(300, 300),
        null=True,
        blank=True,
    )

Parameters

Resize Methods

fit (default)

Maintains aspect ratio. Thumbnail fits within the specified size but may be smaller in one dimension.

# A 400x100 image with size=(150, 150) becomes 150x37
thumbnail = AdvanceThumbnailField(
    source_field='image',
    size=(150, 150),
    resize_method='fit',  # default
)

fill / cover

Guarantees exact dimensions by cropping. Use this when you need thumbnails to be exactly the specified size.

# A 400x100 image with size=(150, 150) becomes exactly 150x150
thumbnail = AdvanceThumbnailField(
    source_field='image',
    size=(150, 150),
    resize_method='fill',  # guarantees 150x150
)

Usage Examples

Basic Usage

from django.db import models
from django_advance_thumbnail import AdvanceThumbnailField

class Article(models.Model):
    image = models.ImageField(upload_to='articles/')
    thumbnail = AdvanceThumbnailField(
        source_field='image',
        upload_to='thumbnails/',
        size=(300, 300),
        null=True,
        blank=True,
    )

Multiple Thumbnails

class Product(models.Model):
    image = models.ImageField(upload_to='products/')

    # Small thumbnail for listings (fit mode)
    thumbnail_small = AdvanceThumbnailField(
        source_field='image',
        upload_to='thumbnails/small/',
        size=(100, 100),
        resize_method='fit',
    )

    # Large thumbnail for detail page (exact dimensions)
    thumbnail_large = AdvanceThumbnailField(
        source_field='image',
        upload_to='thumbnails/large/',
        size=(400, 400),
        resize_method='fill',
    )

Using Constants

from django_advance_thumbnail import AdvanceThumbnailField, RESIZE_FIT, RESIZE_FILL

thumbnail = AdvanceThumbnailField(
    source_field='image',
    size=(200, 200),
    resize_method=RESIZE_FILL,
)

Management Commands

Generate Thumbnails

Generate thumbnails for existing images (use when adding field to existing models):

# All models
python manage.py generate_thumbnails

# Specific model
python manage.py generate_thumbnails --model myapp.Product

# Force regenerate existing
python manage.py generate_thumbnails --force

# Preview without changes
python manage.py generate_thumbnails --dry-run

Regenerate Thumbnails

Regenerate thumbnails after changing size or resize_method:

# Detect and regenerate changed
python manage.py regenerate_thumbnails

# Force regenerate all
python manage.py regenerate_thumbnails --force

# Clear cache first
python manage.py regenerate_thumbnails --clear-cache

Smart Regeneration

Thumbnails are only regenerated when:

• Source image changes
• size parameter changes
• resize_method parameter changes
• Thumbnail doesn't exist

This is efficient for production - no unnecessary processing.

Change detection uses the cache as a fast path only. A cache miss - a restart, an eviction, or a per-process backend such as LocMemCache - falls back to comparing the stored thumbnail name against the current source, so restarts and extra workers do not produce duplicate thumbnails. Because that fallback only sees filenames, a source replaced under its existing name is not detected without a working shared cache; run regenerate_thumbnails --force in that case.

Thread Safety

Version 2.0+ is fully thread-safe for multi-threaded web servers like gunicorn and uwsgi. The previous signal disconnect/reconnect pattern has been replaced with instance-level flags.

Requirements

• Python >= 3.6
• Django >= 3.0
• Pillow >= 8.0.0

Upgrading to v2.0

See MIGRATION_GUIDE.md for breaking changes and upgrade instructions.

Contact

• Email: mh@mahadihassan.com
• GitHub: @itsmahadi007
• LinkedIn: Mahadi Hassan
• Web: mahadihassan.com

License

MIT License