wagtail/docs/advanced_topics/images/renditions.md

(image_renditions)=

# Generating renditions in Python

Rendered versions of original images generated by the Wagtail `{% image %}` template tag are called "renditions",
and are stored as new image files in the site's `[media]/images` directory on the first invocation.

Image renditions can also be generated dynamically from Python via the native `get_rendition()` method, for example:

```python
newimage = myimage.get_rendition('fill-300x150|jpegquality-60')
```

If `myimage` had a filename of `foo.jpg`, a new rendition of the image file called
`foo.fill-300x150.jpegquality-60.jpg` would be generated and saved into the site's `[media]/images` directory.
Argument options are identical to the `{% image %}` template tag's filter spec, and should be separated with `|`.

The generated `Rendition` object will have properties specific to that version of the image, such as
`url`, `width` and `height`, so something like this could be used in an API generator, for example:

```python
url = myimage.get_rendition('fill-300x186|jpegquality-60').url
```

Properties belonging to the original image from which the generated Rendition was created, such as `title`, can
be accessed through the Rendition's `image` property:

```python
    >>> newimage.image.title
    'Blue Sky'
    >>> newimage.image.is_landscape()
    True
```

See also: [](image_tag)

(prefetching_image_renditions)=

## Prefetching image renditions

```{versionadded} 3.0
This following guidance is only applicable in Wagtail versions 3.0 and above.
```

When using a queryset to render a list of objects with images, you can make use of Django's built-in `prefetch_related()` queryset method to prefetch the renditions needed for rendering with a single additional query. For long lists of items, or where multiple renditions are used for each item, this can provide a significant boost to performance.

For example, say you were rendering a list of events (with thumbnail images for each). Your code might look something like this:

```python
def get_events():
    return EventPage.objects.live().select_related("listing_image")
```

The above can be modified slightly to prefetch the renditions for listing images:

```python
def get_events():
    return EventPage.objects.live().select_related("listing_image").prefetch_related("listing_image__renditions")
```

If images in your project tend to have very large numbers of renditions, and you know in advance the ones you need, you might want to consider using a `Prefetch` object to select only the renditions you need for rendering. For example:

```python
from django.db.models import Prefetch
from wagtail.images import get_image_model


def get_events():
    # These are the renditions required for rendering
    renditions_queryset = get_image_model().get_rendition_model().objects.filter(
        filter_spec__in=["fill-300x186", "fill-600x400", "fill-940x680"]
    )

    # `Prefetch` is used to fetch only the required renditions
    return EventPage.objects.live().select_related("listing_image").prefetch_related(
        Prefetch("listing_image__renditions", queryset=renditions_queryset)
    )
```

(image_rendition_methods)=

## Model methods involved in rendition generation

```{versionadded} 3.0
The following method references are only applicable to Wagtail versions 3.0 and above.
```

The following `AbstractImage` model methods are involved in finding and generating a renditions. If using a custom image model, you can customise the behaviour of either of these methods by overriding them on your model:

```{eval-rst}
.. automodule:: wagtail.images.models

.. class:: AbstractImage
    :noindex:

    .. automethod:: get_rendition

    .. automethod:: find_existing_rendition

    .. automethod:: create_rendition

    .. automethod:: generate_rendition_file
```