{"id":6344,"library":"django-imagekit","title":"django-imagekit","description":"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.","status":"active","version":"6.1.0","language":"en","source_language":"en","source_url":"https://github.com/matthewwithanm/django-imagekit/","tags":["django","image processing","thumbnailing","orm","file uploads"],"install":[{"cmd":"pip install django-imagekit Pillow","lang":"bash","label":"Install with Pillow"},{"cmd":"INSTALLED_APPS = [\n    # ...\n    'imagekit',\n    # ...\n]","lang":"python","label":"Add to INSTALLED_APPS"}],"dependencies":[{"reason":"Core image manipulation library; django-imagekit depends on it for all image processing operations. Must be installed separately.","package":"Pillow","optional":false},{"reason":"Framework dependency.","package":"django","optional":false},{"reason":"Provides the underlying image processors and utilities that django-imagekit uses.","package":"pilkit","optional":false}],"imports":[{"note":"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.","wrong":"from imagekit.models import ImageSpecField(image_field='...')","symbol":"ImageSpecField","correct":"from imagekit.models import ImageSpecField"},{"note":"While 'imagekit.models' might work due to internal imports, the canonical path for ProcessedImageField is 'imagekit.models.fields'.","wrong":"from imagekit.models import ProcessedImageField","symbol":"ProcessedImageField","correct":"from imagekit.models.fields import ProcessedImageField"},{"note":"Processors are typically imported from `imagekit.processors` which then imports them from `PILKit`.","symbol":"ResizeToFill","correct":"from imagekit.processors import ResizeToFill"}],"quickstart":{"code":"from django.db import models\nfrom imagekit.models import ImageSpecField, ProcessedImageField\nfrom imagekit.processors import ResizeToFill\nfrom django.conf import settings\n\n# NOTE: This code snippet demonstrates model field definitions.\n# For a runnable example, you need a full Django project setup\n# including settings.py (e.g., MEDIA_ROOT, MEDIA_URL, INSTALLED_APPS).\n# In settings.py, ensure 'imagekit' is in INSTALLED_APPS.\n\n# Example Django Model\nclass Product(models.Model):\n    name = models.CharField(max_length=255)\n    # Original image field where users upload their files\n    original_photo = models.ImageField(upload_to='products', blank=True, null=True)\n    \n    # ImageSpecField for an automatically generated thumbnail\n    # This field does not create a database column, but provides an interface\n    # to a dynamically generated image based on 'original_photo'.\n    thumbnail = ImageSpecField(\n        source='original_photo',\n        processors=[ResizeToFill(100, 100)],\n        format='JPEG',\n        options={'quality': 75}\n    )\n\n    # ProcessedImageField for a product detail image, directly saved.\n    # This field creates a database column and stores the path to the\n    # processed image file. This is useful if you want to save a processed\n    # version directly or don't need the original.\n    detail_image = ProcessedImageField(\n        upload_to='product_details',\n        processors=[ResizeToFill(800, 600)],\n        format='PNG',\n        options={'quality': 85},\n        blank=True, \n        null=True\n    )\n\n    def __str__(self):\n        return self.name\n\n# To use:\n# product = Product.objects.create(name='Example', original_photo='path/to/image.jpg')\n# # Accessing .url will trigger image generation (for ImageSpecField) or retrieve path (for ProcessedImageField)\n# print(product.thumbnail.url)\n# print(product.detail_image.url)\n","lang":"python","description":"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`."},"warnings":[{"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.","message":"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.","severity":"breaking","affected_versions":"6.0, 6.1"},{"fix":"Update your `ImageSpecField` definitions to use `source='your_image_field_name'` instead of `image_field='your_image_field_name'`.","message":"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.","severity":"breaking","affected_versions":"< 4.0"},{"fix":"To explicitly control the cache timeout, set the `IMAGEKIT_CACHE_TIMEOUT` setting in your `settings.py`.","message":"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).","severity":"breaking","affected_versions":"6.0, 6.1"},{"fix":"Avoid importing from `imagekit.templatetags.compat`. If absolutely necessary, update imports to `imagekit.compat`, but consider refactoring to use public APIs.","message":"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.","severity":"deprecated","affected_versions":"6.0, 6.1"},{"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 %}`.","message":"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.","severity":"gotcha","affected_versions":"All"}],"env_vars":null,"last_verified":"2026-04-15T00:00:00.000Z","next_check":"2026-07-14T00:00:00.000Z"}