How you can use Wagtail to optimize your images
AI won't automatically optimize your images for you, so here's how you can make it happen with and without AI tooling
I recently used Claude Code to import some new styles for the Wagtail Space 2026 website from Figma. This experiment was largely successful. It took me a week last year, and it only took two days this year. That was largely because the API in the Figma MCP plugin cut down on a lot of copying and pasting. Even without the AI model, that new way to access Figma is a huge timesaver.
But there are two things that went a bit sideways. First, instead of removing the 2025 styles like I asked it to, the AI made all of them transparent. It reminded me of a teenager shoving all their stuff under their bed and declaring their room is clean. After I corrected that, I reviewed the code and thought I had cleaned up everything the AI missed. But when my co-worker Chris took a look, he pointed out something that made me do a facepalm: the AI imported the largest, most inefficient file formats possible from Figma. There was no image optimization whatsoever, and that's because I was so happy about how much time I was saving that I forgot to make image optimization a priority.
Why you should always optimize your images
I wrote a blog a while back on how you should switch to the webp image format whenever you can. It provides the best balance between image quality and size. Since I wrote that blog, webp adoption has expanded, but there is still friction with some major platforms that really should be offering webp support by now (cough, cough, looking at you Google Slides).
My recommendation for using webp still stands. Using smaller, more efficient image formats is not just better for the environment, but it's also better for your users as well because smaller images load faster. This is particularly helpful if you have lots of people accessing your website on mobile devices or slower inter etc connections. Also, increasing your website's speed can help improve your search ranking. Even though AI is also changing how people use search, SEO still makes a difference.
Fortunately, Wagtail makes it pretty easy to use the webp image format in your templates. If you're using AI to assist you like I did though, you're going to have to tell the AI that using the webp is a priority. Let's review how you can optimize images without AI first though, and then I'll share an AI skill at the end that will direct your AI agent to use webp.
Use image tags to specify an output format
Wagtail makes it easy to decide what image format the browser will render your images as. You can add image formats to your templates by modifying the {% image %} tags like this:
{% image page.photo format-avif %} {% image page.photo format-webp %} {% image page.photo format-jpeg %} {% image page.photo format-png %} {% image page.photo format-gif %} {% image page.photo format-ico %} {% image page.photo format-avif-lossless %} {% image page.photo format-webp-lossless %}
The most efficient formats on those lists are AVIF and webp with AVIF being the best for small file sizes. AVIF is still new enough though that you'll need to use fallback image formats to support older browser versions. The lossless versions of these formats are meant to compress images without losing any image quality, but the file sizes might be bigger. You'll need to experiment a bit to see which output works best for your project.
Note that if you have sharp editors who know how to use the inspect feature in browsers to check image formats and sizes, they are going to notice that the file format they uploaded doesn't match the output. In that case, it might be worth your time to add a little help text to image fields to tell them the final format those images will have.
Use resize methods
Resize methods help optimize your images by making sure browsers won't load images that are larger than necessary. If you have editors with a tendency to upload large, high-res images, then resize rules will automatically adjust those images to more reasonable size. If you're working with a designer, setting rules that preserve design proportions will also make them really happy (and we love happy designers).
Wagtail has a lot of resize methods, but here are a few examples of how they work:
{% image page.photo max-1000x500 %} {% image page.photo min-500x200 %} {% image page.photo width-640 %} {% image page.photo height-480 %}
One other to know about Wagtail's resize methods is that they can change your image file format, which is why you should add a format output to all your image tags.
Use the picture tag
Wagtail actually has a pretty great feature where you can support multiple formats with a single line of code. This is the {% picture %} tag.
The picture tag is a great way to prioritize smaller, more efficient image formats but also provide fallback options if the user is accessing your website through a browser that doesn't support the newer formats. You get to set the priority order too. For example, this code will prioritize AVIF and then webp and then PNG.
{% picture page.photo format-{avif,webp,png} width-400 %}
So the HTML output would look something like this:
<picture> <source srcset="/media/images/pied-wagtail.width-400.avif" type="image/avif"> <source srcset="/media/images/pied-wagtail.width-400.webp" type="image/webp"> <img src="/media/images/pied-wagtail.width-400.png" alt="A pied Wagtail" width="400" height="300"> </picture>
You can go a step further with the picture tag by providing multiple sizes for the browser to select from as well. That way the smallest image possible will be the one that's rendered. This also gives you the option to support higher image resolutions as well but only render larger images when they are really necessary. After all, chances are high that most people are going to access your website on their phones instead of their smart TVs.
Here's how you can add sizes to the {% picture %} tag:
{% picture page.photo format-{avif,webp,png} width-{400,800} sizes="80vw" %}
That will lead to an HTML output that looks something like this:
<picture> <source sizes="80vw" srcset="/media/images/pied- wagtail.width-400.avif 400w, /media/images/pied -wagtail.width-800.avif 800w" type="image/avif"> <source sizes="80vw" srcset="/media/images/pied- wagtail.width-400.webp 400w, /media/images/pied- wagtail.width-800.webp 800w" type="image/webp"> <img sizes="80vw" srcset="/media/images/pied- wagtail.width-400.jpg 400w, /media/images/pied- wagtail.width-800.png 800w" src="/media/ images/pied-wagtail.width-400.png" alt="A pied Wagtail" width="400" height="300"> </picture>
Remember that rich text images are different
Editors will be able to insert images through the rich text block unless you switch that feature off. When images are added that way, you don't have as much fine-grained control over how images are displayed and rendered. Wagtail has default methods for how those images are displayed and you can customize those defaults if you want more control over the final image formats and sizes. Just resist the urge to mess with your editors by swapping the left and right alignments. That will not find it funny, and trust me when I say that irritating an editor on a deadline is about as smart as poking a cobra in the eye. Don't do it.
Use libwebp or Squoosh to convert your static images to webp
The images editors add to Wagtail aren't the only ones that need to be optimized. You need to optimize all the static images for your project as well. I still highly recommend webp for this. Just don't convert your favicons or SVG files to webp. That will break things.
If you like drag and drop, then Squoosh is a great tool for converting files to webp. If you have a larger batch of files than the libwp command line tool is a great one for converting files in batches. Here is a link to an example of a script you can use to convert your existing static files.
An AI skill to prioritize webp
I created this AI skill to encourage my AI agents to use webp in the future. This skill is a pretty basic one and you could probably copy some of this language into your project specs instead of making it a standalone skill. I didn't have time to test a more extensive skill that incorporates all of this image optimization advice. If I refine the skill, I'll be sure to update it. Here is a skill you can feed to your AI along with this blog post.
--- name: webp-image-optimization description: Set the format of your images as webp and change as many static files to the webp format as possible. license: MIT --- # Wagtail webp Image Optimization ## Overview A skill to encourage agents to use the webp image format as much as possible in Wagtail projects. ## Methodology ### Goals - Set the output format for every image tag in a Wagtail project to webp - Convert static images in a Wagtail project to webp usind libwp ### Guardrails - Make only changes to image files or template files - Do not make any changes to models or settings. - When converting images from other formats to webp, do not delete the original images unless the user requests the images be deleted. - Do not convert static images with the SVG format or any files with the extension .svg to webp. - Do not convert favicons or any files within a favicons directory - Do not convert or modify tags for social media meta data to webp. ### Reference data sources Always fetch latest information from the official Wagtail and libwebp docs if possible. - [How to use images in templates](https://github.com/wagtail/wagtail/wiki/Release-schedule) - [llms.txt index of developer docs pages](https://docs.wagtail.org/en/latest/llms.txt) - [libwebp documentation](https://chromium.googlesource.com/webm/libwebp/) ### Reporting Optimizing images is important and it’s critical you provide clear information to the user throughout converting images and updating the image format outputs. Provide a comprehensive report at the end that tells the user how many image tags have been updated to use the webp format and how many images have been converted to webp. - Use text formatting if supported (tables, lists, Markdown links) - Link directly to release notes and other documentation pages where relevant. - When sharing docs references in reporting, make sure to link to the HTML pages (.html, not .html.md for developer docs; and remove /markdown/ from user guide URLs). - Report on both your methodology, and the outcome. - Use artifacts in addition to messages if supported. ### Commit and pull request strategy Do not create commits or pull requests unless requested by the user. ### Definition of done To adapt from the specifics of the project: - All image tags have the webp format outputs - All static images that are not SVG or files ending with .svg have been converted to webp. - A report has been created for the user to tell them what has been done. ## Steps ### Add an output format to all of the image tags - [ ] Add `format-webp` to all {% image %} tags in the Wagtail project ### Convert static images to webp - [ ] Locate the static images for the project by searching for a directory labeled static or a directory labeled img - [ ] Determine the file extensions of the image files of that directory - [ ] Leave any SVG files or any files ending with the extension .svg alone - [ ] Leave any favicons or any files within a directory labeled favicons alone - [ ] Use cwebp to convert files with a quality of 85 and a method of 6. - [ ] Update references to the original static files to use the new webp file format. Note any warnings or errors for the user and ask for their input. ### Create report - [ ] Provide a report that tells the user how many image tags have been updated to use the webp format and how many images have been converted to webp
This Week in Wagtail
A weeklyish newsletter with Wagtail tips, news, and more.