Installation is easy with pip:

$ pip install django-versatileimagefield

Python Compatibility

  • 3.6.x
  • 3.7.x
  • 3.8.x
  • 3.9.x

Django Compatibility

  • 2.0.x
  • 2.2.x
  • 3.0.x
  • 3.1.x
  • 3.2.x


  • Pillow>= 2.4.x

django-versatileimagefield depends on the excellent Pillow fork of PIL. If you already have PIL installed, it is recommended you uninstall it prior to installing django-versatileimagefield:

$ pip uninstall PIL
$ pip install django-versatileimagefield


django-versatileimagefield will not install django.

If you are developing on Windows you’ll need to install python-magic-bin as well:

$ pip install python-magic-bin==0.4.1


After installation completes, add 'versatileimagefield' to INSTALLED_APPS:

    # All your other apps here


A dictionary that allows you to fine-tune how django-versatileimagefield works:

    # The amount of time, in seconds, that references to created images
    # should be stored in the cache. Defaults to `2592000` (30 days)
    'cache_length': 2592000,
    # The name of the cache you'd like `django-versatileimagefield` to use.
    # Defaults to 'versatileimagefield_cache'. If no cache exists with the name
    # provided, the 'default' cache will be used instead.
    'cache_name': 'versatileimagefield_cache',
    # The save quality of modified JPEG images. More info here:
    # Defaults to 70
    'jpeg_resize_quality': 70,
    # The name of the top-level folder within storage classes to save all
    # sized images. Defaults to '__sized__'
    'sized_directory_name': '__sized__',
    # The name of the directory to save all filtered images within.
    # Defaults to '__filtered__':
    'filtered_directory_name': '__filtered__',
    # The name of the directory to save placeholder images within.
    # Defaults to '__placeholder__':
    'placeholder_directory_name': '__placeholder__',
    # Whether or not to create new images on-the-fly. Set this to `False` for
    # speedy performance but don't forget to 'pre-warm' to ensure they're
    # created and available at the appropriate URL.
    'create_images_on_demand': True,
    # A dot-notated python path string to a function that processes sized
    # image keys. Typically used to md5-ify the 'image key' portion of the
    # filename, giving each a uniform length.
    # `django-versatileimagefield` ships with two post processors:
    # 1. 'versatileimagefield.processors.md5' Returns a full length (32 char)
    #    md5 hash of `image_key`.
    # 2. 'versatileimagefield.processors.md5_16' Returns the first 16 chars
    #    of the 32 character md5 hash of `image_key`.
    # By default, image_keys are unprocessed. To write your own processor,
    # just define a function (that can be imported from your project's
    # python path) that takes a single argument, `image_key` and returns
    # a string.
    'image_key_post_processor': None,
    # Whether to create progressive JPEGs. Read more about progressive JPEGs
    # here:
    'progressive_jpeg': False


A boolean that signifies whether optional (blank=True) VersatileImageField fields that do not specify a placeholder image should return URLs.


A dictionary used to specify ‘Rendition Key Sets’ that are used for both serialization or as a way to ‘warm’ image files so they don’t need to be created on demand (i.e. when settings.VERSATILEIMAGEFIELD_SETTINGS['create_images_on_demand'] is set to False) which will greatly improve the overall performance of your app. Here’s an example:

    'image_gallery': [
        ('gallery_large', 'crop__800x450'),
        ('gallery_square_small', 'crop__50x50')
    'primary_image_detail': [
        ('hero', 'crop__600x283'),
        ('social', 'thumbnail__800x800')
    'primary_image_list': [
        ('list', 'crop__400x225'),
    'headshot': [
        ('headshot_small', 'crop__150x175'),

Each key in VERSATILEIMAGEFIELD_RENDITION_KEY_SETS signifies a ‘Rendition Key Set’, a list comprised of 2-tuples wherein the first position is a serialization-friendly name of an image rendition and the second position is a ‘Rendition Key’ (which dictates how the original image should be modified).

Writing Rendition Keys

Rendition Keys are intuitive and easy to write, simply swap in double-underscores for the dot-notated paths you’d use in the shell or in templates. Examples:

Intended image As ‘Rendition Key’ In the shell In templates
400px by 400px Crop 'crop__400x400' instance.image_field.crop['400x400'].url {{ instance.image_field.crop.400x400 }}
100px by 100px Thumbnail 'thumbnail__100x100' instance.image_field.thumbnail['100x100'].url {{ instance.image_field.thumbnail.100x100 }}
Inverted Image (Full Size) 'filters__invert' instance.image_field.filters.invert.url {{ instance.image_field.filters.invert }}
Inverted Image, 50px by 50px crop 'filters__invert__crop__50x50' instance.image_field.filters.invert.crop['50x50'].url {{ instance.image_field.filters.invert.crop.50x50 }}

Using Rendition Key Sets

Rendition Key sets are useful! Read up on how they can help you…