Welcome to django-versatileimagefield’s documentation!

Travis CI Status Coverage Status Supported Python versions Downloads Latest Version

A drop-in replacement for django’s ImageField that provides a flexible, intuitive and easily-extensible interface for quickly creating new images from the one assigned to your field.

In A Nutshell

  • Creates images anywhere you need them: not just in templates.

  • Non-destructive: Your original image is never modified.

  • Sizer and Filter framework: enables you to quickly add new – or modify existing – ways to create new images:

    • Sizers create images with new sizes and/or aspect ratios
    • Filters change the appearance of an image
  • Sizers can be chained onto Filters: Use case: give me a black-and-white, 400px by 400px square crop of this image.

  • Primary Point of Interest (PPOI) support: provides a way to specify where the ‘primary point of interest’ of each individual image is – a value which is available to all Sizers and Filters. Use case: sometimes you want the ‘crop centerpoint’ to be somewhere other than the center of an image. Includes a user-friendly formfield/widget for selecting PPOI in the admin (or anywhere else you use ModelForms).

  • Works with any storage: Stores the images it creates within the same storage class as your field . Works great with external storage (like Amazon S3).

  • Fully interchangeable with ImageField: you can easily remove VersatileImageField from your project’s models whenever you’d like.

  • Integrated caching: References to created images are stored in the cache, keeping your application running quickly and efficiently.

  • Django REST Framework support: Serialize multiple image renditions from a single VersatileImageField.

  • Flexible and fast: On-demand image creation can be toggled in your settings file allowing you to turn it off when you need your application to run as quickly as possible.

Release Notes


  • Squashed a bug that was causing the admin ‘click’ widget to intermittently fail
  • Simplified requirements installation (which makes django-versatileimagefield installable by pip<=1.6)


  • Changed PPOIField to be editable=False by default to address a bug that consistently raised ValidationError in ModelForms and the admin


  • Squashed a bug that prevented PPOIField from serializing correctly


  • Squashed an installation bug with pip 6+


  • Added Python 3.3 & 3.4 compatibility
  • Improved cropping with extreme PPOI values


  • Dropped support for Django 1.5.x
  • Introducing per-field placeholder image image support! (Note: global placeholder support has been deprecated.)


  • Squashed a pip installation bug.



  • Ensuring admin widget-dependent thumbnail images are created even if VERSATILEIMAGEFIELD_SETTINGS['create_on_demand'] is set to False



  • Squashed CroppedImage bug that was causing black stripes to appear on crops of images with PPOI values that were to the right and/or bottom of center (greater-than 0.5).


  • Overhauled how CroppedImage processes PPOI value when creating cropped images. This new approach yields significantly more accurate results than using the previously utilized ImageOps.fit function, especially when dealing with PPOI values located near the edges of an image or aspect ratios that differ significantly from the original image.
  • Improved PPOI validation
  • Squashed unset VERSATILEIMAGEFIELD_SETTINGS['global_placeholder_image'] bug.
  • Set crop Sizer default resample to PIL.Image.ANTIALIAS


  • Added support for auto-rotation during pre-processing as dictated by ‘Orientation’ EXIF data, if available.
  • Added release notes to docs


  • Removed redundant javascript from ppoi ‘click’ widget (thanks, @skumar!)


  • Converted giant README into Sphinx-friendly RST
  • Docs added to readthedocs


  • Initial open source release

Roadmap to v1.0

  • Programmatically delete images created by VersatileImageField (including clearing their connected cache keys)