wagtail/docs/advanced_topics/images/custom_image_model.md

(custom_image_model)=

Custom image models

The Image model can be customized, allowing additional fields to be added to images.

To do this, you need to add two models to your project:

• The image model itself that inherits from wagtail.images.models.AbstractImage. This is where you would add your additional fields
• The renditions model that inherits from wagtail.images.models.AbstractRendition. This is used to store renditions for the new model.

Here's an example:

# models.py
from django.db import models

from wagtail.images.models import Image, AbstractImage, AbstractRendition


class CustomImage(AbstractImage):
    # Add any extra fields to image here

    # To add a caption field:
    # caption = models.CharField(max_length=255, blank=True)

    admin_form_fields = Image.admin_form_fields + (
        # Then add the field names here to make them appear in the form:
        # 'caption',
    )


class CustomRendition(AbstractRendition):
    image = models.ForeignKey(CustomImage, on_delete=models.CASCADE, related_name='renditions')

    class Meta:
        unique_together = (
            ('image', 'filter_spec', 'focal_point_key'),
        )

Then set the WAGTAILIMAGES_IMAGE_MODEL setting to point to it:

WAGTAILIMAGES_IMAGE_MODEL = 'images.CustomImage'

Migrating from the builtin image model

When changing an existing site to use a custom image model, no images will be copied to the new model automatically. Copying old images to the new model would need to be done manually with a {ref}data migration <django:data-migrations>.

Any templates that reference the builtin image model will still continue to work as before but would need to be updated in order to see any new images.

(custom_image_model_referring_to_image_model)=

Referring to the image model

.. module:: wagtail.images

.. autofunction:: get_image_model

.. autofunction:: get_image_model_string

(custom_image_model_upload_location)=

Overriding the upload location

The following methods can be overridden on your custom Image or Rendition models to customize how the original and rendition image files get stored.

.. automodule:: wagtail.images.models
    :no-index:

.. class:: AbstractImage
    :no-index-entry:

    .. automethod:: get_upload_to

.. class:: AbstractRendition
    :no-index-entry:

    .. automethod:: get_upload_to

Refer to the Django FileField.upload_to function to further understand how the function works.