django-imagekit

6.1.0 · active · verified Wed Apr 15

Django-imagekit is a Django application for automated image processing on models. It allows developers to define "specs" for variations of uploaded images, such as thumbnails or black-and-white versions, which are generated on demand. The library maintains a moderate release cadence, often aligning with new Django and Python version releases to ensure compatibility and leverage modern features.

Warnings

breaking Major versions of `django-imagekit` often drop support for older Python and Django versions. Version 6.x (including 6.1.0) explicitly supports Python 3.9, 3.10, 3.11, 3.12, 3.13, 3.14 and Django 3.2, 4.2, 5.2, 6.0. Upgrading from older `django-imagekit` versions might require updating your Python and Django environments.
Fix: Consult the release notes for your target `django-imagekit` version and upgrade your Python and Django installations accordingly. For 6.x, ensure Python >= 3.9 and Django >= 3.2.
breaking The `image_field` argument for `ImageSpecField` was renamed to `source` in `django-imagekit` versions 3.x/4.x. Using `image_field` in current versions will lead to errors.
Fix: Update your `ImageSpecField` definitions to use `source='your_image_field_name'` instead of `image_field='your_image_field_name'`.
breaking In version 6.0, if you previously configured `IMAGEKIT_CACHE_BACKEND` and relied on a `TIMEOUT` setting within it, this setting is no longer respected. The default timeout in production (`DEBUG=False`) is now `None` (forever).
Fix: To explicitly control the cache timeout, set the `IMAGEKIT_CACHE_TIMEOUT` setting in your `settings.py`.
deprecated The internal API module `imagekit.templatetags.compat` has been moved to `imagekit.compat` in version 6.0. While this was considered an internal API not meant for direct use, any direct imports will break.
Fix: Avoid importing from `imagekit.templatetags.compat`. If absolutely necessary, update imports to `imagekit.compat`, but consider refactoring to use public APIs.
gotcha Accessing the `.url` property of an `ImageSpecField` or `ProcessedImageField` when the underlying source image file is missing or invalid (e.g., an empty `ImageField`) can raise an exception and potentially crash the page. This mirrors Django's `ImageField` behavior.
Fix: Always check for the existence of the source image before attempting to access the processed image's URL in templates, e.g., `{% if object.original_photo %}<img src="{{ object.thumbnail.url }}">{% endif %}`.

Install

pip install django-imagekit Pillow Install with Pillow
INSTALLED_APPS = [ # ... 'imagekit', # ... ] Add to INSTALLED_APPS

Imports

ImageSpecField
```
from imagekit.models import ImageSpecField
```
The 'image_field' argument for ImageSpecField was renamed to 'source' in versions 3.x/4.x. Using 'image_field' in newer versions will cause errors.
ProcessedImageField
```
from imagekit.models.fields import ProcessedImageField
```
While 'imagekit.models' might work due to internal imports, the canonical path for ProcessedImageField is 'imagekit.models.fields'.
ResizeToFill
```
from imagekit.processors import ResizeToFill
```
Processors are typically imported from `imagekit.processors` which then imports them from `PILKit`.

Quickstart

This quickstart demonstrates how to integrate `django-imagekit` into your Django models. It showcases two primary field types: `ImageSpecField` for on-the-fly image generation from a source field, and `ProcessedImageField` for directly saving a processed image to a new field. Define your desired processors (e.g., resizing, cropping) and format options directly in your model fields. Ensure 'imagekit' is added to your Django project's `INSTALLED_APPS`.

from django.db import models
from imagekit.models import ImageSpecField, ProcessedImageField
from imagekit.processors import ResizeToFill
from django.conf import settings

# NOTE: This code snippet demonstrates model field definitions.
# For a runnable example, you need a full Django project setup
# including settings.py (e.g., MEDIA_ROOT, MEDIA_URL, INSTALLED_APPS).
# In settings.py, ensure 'imagekit' is in INSTALLED_APPS.

# Example Django Model
class Product(models.Model):
    name = models.CharField(max_length=255)
    # Original image field where users upload their files
    original_photo = models.ImageField(upload_to='products', blank=True, null=True)
    
    # ImageSpecField for an automatically generated thumbnail
    # This field does not create a database column, but provides an interface
    # to a dynamically generated image based on 'original_photo'.
    thumbnail = ImageSpecField(
        source='original_photo',
        processors=[ResizeToFill(100, 100)],
        format='JPEG',
        options={'quality': 75}
    )

    # ProcessedImageField for a product detail image, directly saved.
    # This field creates a database column and stores the path to the
    # processed image file. This is useful if you want to save a processed
    # version directly or don't need the original.
    detail_image = ProcessedImageField(
        upload_to='product_details',
        processors=[ResizeToFill(800, 600)],
        format='PNG',
        options={'quality': 85},
        blank=True, 
        null=True
    )

    def __str__(self):
        return self.name

# To use:
# product = Product.objects.create(name='Example', original_photo='path/to/image.jpg')
# # Accessing .url will trigger image generation (for ImageSpecField) or retrieve path (for ProcessedImageField)
# print(product.thumbnail.url)
# print(product.detail_image.url)

view raw JSON →