django-versatileimagefield

3.1 verified Fri May 01 auth: no python

A drop-in replacement for Django's ImageField that provides a flexible interface for creating new images (e.g., thumbnails) from the one assigned to the field. Current version: 3.1. Release cadence is irregular; maintained by RespondCreate.

pip install django-versatileimagefield

Common errors

error ModuleNotFoundError: No module named 'versatileimagefield' ↓

cause The package is not installed or not in the Python path.

fix

Run pip install django-versatileimagefield and ensure the app is in INSTALLED_APPS.

error KeyError: 'sizes' ↓

cause Trying to access a non-existent size key on the image field's rendition.

fix

Ensure the size set name is correct (e.g., 'product_gallery' instead of 'gallery'). Check VERSATILEIMAGEFIELD_SETS in settings.

error AttributeError: 'VersatileImageField' object has no attribute 'url' ↓

cause Accessing .url directly on the field (returns a static method, not a string) instead of using the rendition's url.

fix

Use instance.image.url (still works) or call instance.image['thumbnail'].url. The field itself is not a callable.

error ImproperlyConfigured: PPOIField could not be resolved. Check that the field 'image_ppoi' exists on the model. ↓

cause Missing PPOIField definition or mismatch in ppoi_field argument.

fix

Add a PPOIField with the exact name specified in ppoi_field (e.g., image_ppoi = PPOIField()).

error TypeError: 'SizedImageSet' object is not subscriptable ↓

cause Trying to use bracket indexing on a sized image set that has no sizes defined.

fix

Define at least one size in VERSATILEIMAGEFIELD_SETS or use the default sizes.

Warnings

gotcha If you don't add a PPOIField when using ppoi_field, the field will raise an error on first access or S3 upload (key validation fails). ↓

fix Always define a PPOIField with the same name as the ppoi_field argument.

gotcha When using S3 as the storage backend (e.g., django-storages), create_on_demand=False is not supported; always set it to True or omit. The default True is safe. ↓

fix Omit create_on_demand argument or set it to True.

deprecated ImageDetailFilter and 'sizedimage_set' queryset filters are deprecated in favor of the registry API (create_sized_image_url). ↓

fix Use `create_sized_image_url` or the `build_url` method on the image field.

breaking Dropped support for Python 2.7, Django <1.11. Requires Django >=2.2 and Python >=3.5. ↓

fix Upgrade to Python 3.5+ and Django 2.2+.

Imports

VersatileImageField

wrong

from versatileimagefield import VersatileImageField

correct

from versatileimagefield.fields import VersatileImageField

Direct import from top-level package doesn't work; must use submodule.

PPOIField

from versatileimagefield.fields import PPOIField

create_sized_image_url

from versatileimagefield.registry import create_sized_image_url

Quickstart

Define a model with VersatileImageField and associated PPOIField. Then run makemigrations and migrate.

from django.db import models
from versatileimagefield.fields import VersatileImageField, PPOIField

class Product(models.Model):
    name = models.CharField(max_length=255)
    image = VersatileImageField(
        upload_to='products/',
        ppoi_field='image_ppoi'
    )
    image_ppoi = PPOIField()

    class Meta:
        app_label = 'myapp'