{"id":23610,"library":"django-versatileimagefield","title":"django-versatileimagefield","description":"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.","status":"active","version":"3.1","language":"python","source_language":"en","source_url":"https://github.com/respondcreate/django-versatileimagefield","tags":["django","image","thumbnail","versatileimagefield"],"install":[{"cmd":"pip install django-versatileimagefield","lang":"bash","label":"Stable from PyPI"}],"dependencies":[{"reason":"Core dependency; requires Django 2.2+ (including 4.x)","package":"Django","optional":false},{"reason":"Required for image processing","package":"Pillow","optional":false}],"imports":[{"note":"Direct import from top-level package doesn't work; must use submodule.","wrong":"from versatileimagefield import VersatileImageField","symbol":"VersatileImageField","correct":"from versatileimagefield.fields import VersatileImageField"},{"note":"","wrong":"","symbol":"PPOIField","correct":"from versatileimagefield.fields import PPOIField"},{"note":"","wrong":"","symbol":"create_sized_image_url","correct":"from versatileimagefield.registry import create_sized_image_url"}],"quickstart":{"code":"from django.db import models\nfrom versatileimagefield.fields import VersatileImageField, PPOIField\n\nclass Product(models.Model):\n    name = models.CharField(max_length=255)\n    image = VersatileImageField(\n        upload_to='products/',\n        ppoi_field='image_ppoi'\n    )\n    image_ppoi = PPOIField()\n\n    class Meta:\n        app_label = 'myapp'","lang":"python","description":"Define a model with VersatileImageField and associated PPOIField. Then run makemigrations and migrate."},"warnings":[{"fix":"Always define a PPOIField with the same name as the ppoi_field argument.","message":"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).","severity":"gotcha","affected_versions":"all"},{"fix":"Omit create_on_demand argument or set it to True.","message":"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.","severity":"gotcha","affected_versions":"all"},{"fix":"Use `create_sized_image_url` or the `build_url` method on the image field.","message":"ImageDetailFilter and 'sizedimage_set' queryset filters are deprecated in favor of the registry API (create_sized_image_url).","severity":"deprecated","affected_versions":"2.0+"},{"fix":"Upgrade to Python 3.5+ and Django 2.2+.","message":"Dropped support for Python 2.7, Django <1.11. Requires Django >=2.2 and Python >=3.5.","severity":"breaking","affected_versions":"2.0+"}],"env_vars":null,"last_verified":"2026-05-01T00:00:00.000Z","next_check":"2026-07-30T00:00:00.000Z","problems":[{"fix":"Run `pip install django-versatileimagefield` and ensure the app is in INSTALLED_APPS.","cause":"The package is not installed or not in the Python path.","error":"ModuleNotFoundError: No module named 'versatileimagefield'"},{"fix":"Ensure the size set name is correct (e.g., 'product_gallery' instead of 'gallery'). Check VERSATILEIMAGEFIELD_SETS in settings.","cause":"Trying to access a non-existent size key on the image field's rendition.","error":"KeyError: 'sizes'"},{"fix":"Use `instance.image.url` (still works) or call `instance.image['thumbnail'].url`. The field itself is not a callable.","cause":"Accessing .url directly on the field (returns a static method, not a string) instead of using the rendition's url.","error":"AttributeError: 'VersatileImageField' object has no attribute 'url'"},{"fix":"Add a PPOIField with the exact name specified in ppoi_field (e.g., image_ppoi = PPOIField()).","cause":"Missing PPOIField definition or mismatch in ppoi_field argument.","error":"ImproperlyConfigured: PPOIField could not be resolved. Check that the field 'image_ppoi' exists on the model."},{"fix":"Define at least one size in VERSATILEIMAGEFIELD_SETS or use the default sizes.","cause":"Trying to use bracket indexing on a sized image set that has no sizes defined.","error":"TypeError: 'SizedImageSet' object is not subscriptable"}],"ecosystem":"pypi","meta_description":null,"install_score":null,"install_tag":null,"quickstart_score":null,"quickstart_tag":null}