Guide for Magefan AVIF Images for Magento

Magefan AVIF Images for Magento automatically converts your GIF, PNG and JPG images to the next-gen AVIF format, without deleting or overwriting the originals. AVIF files offer much smaller size than JPG, PNG and even WebP. So pages load faster, while browsers that don't support AVIF format keep receiving the original images.

In this guide, you'll learn how to configure all available extension options, set conversion quality, exclude files from conversion, and monitor AVIF images generation on your store.

Installation & Updates

To install the AVIF Images extension for Magento, follow the instructions from the Magefan extensions management guide.

General AVIF Conversion Settings

Once you install the extension, navigate to Stores > Configuration > Magefan Extensions > AVIF Images to configure it.

Quality settings

Define how much to compress AVIF images and what metadata they keep.

• Enabled — turns the extension on or off. When disabled, no AVIF images are generated, and no already converted AVIF images are loaded on the frontend.
• Quality (1-100) — sets the compression level of the generated AVIF images. The default value is 85.

Use a higher value (90-100) for the best visual quality, but keep in mind that the higher the quality, the bigger the size of the images. Lower the value if you want smaller files with a slightly lower quality.

• Image Metadata — a comma-separated list of metadata to copy from the original image to the AVIF file. Valid values: all, none, exif, icc, xmp. The default is none.

The more metadata you include, the bigger the converted AVIF image. So only add what you actually need, e.g. icc if you rely on colour profiles.

Generation mode

Define how and when to generate AVIF images.

• AVIF Generation Mode — defines how AVIF images are generated:

1. Page Load — AVIF images are generated while a page is loaded (rendered).
2. Cron — images are converted to AVIF by cron on a set schedule.
3. Page Load & Cron — both modes combined.
4. Manually by CLI command — images are converted only when you run the CLI command for AVIF conversion.

• Asynchronous AVIF Generation (on Page Load) — if set to Yes, AVIF images aren't generated during page loading. They're generated asynchronously, only when the image file is requested through pub/get.php. This avoids any delay on page load, even for stores with large catalogs and image volumes correspondingly.

Skip images and folders

Exclude specific files or entire folders from AVIF conversion to save resources and conversion time.

• Skip Media Folders — a list of files and folders inside the media directory that won't be converted.

• Skip Static Folders — a list of files and folders in the static (theme) directory that won't be converted.

By default, media/captcha is already added to Skip Media Folders, since CAPTCHA images don't need AVIF conversion.

AVIF cache

• Clean Converted Images Cache — deletes all previously generated AVIF images. Use this option whenever you change the Quality score or Image Metadata settings. Then save the settings to trigger image regeneration with the new values.

Advanced AVIF Conversion Settings

These settings cover custom image sources across your Magento store: picture tags, page builder content, CSS backgrounds, third-party APIs, and external URLs.

• Use PICTURE Tag to Show AVIF — wraps AVIF images in a <picture> tag so browsers that don't support AVIF automatically fall back to the original images.
• Convert HTML Picture Tag Images — converts the images inside <picture> tags.
• Convert CSS Background Images — converts images used as CSS backgrounds inside an HTML tag style attribute.

• Convert Images and Sliders Inserted via Magento Page Builder — converts images and slider content added through the default Magento Page Builder.
• Convert Images in GraphQL Requests — converts images returned by GraphQL to AVIF for headless and PWA storefronts.
• Convert Images in REST API Requests — converts images returned by REST API requests to AVIF for custom applications.

• Convert Images From External Websites — if you insert images from other websites (e.g. a WordPress blog) and want them converted to AVIF as well, add each website base URL on a new line.

Monitoring and Regenerating AVIF Images

Once the Magefan AVIF extension starts converting images, you can track progress and manage each file from the Images grid. Navigate to System > AVIF Optimized Images > Images to open it.

AVIF Images dashboard

At the top of the page, find a summary of the AVIF conversion activity on your store:

• Optimization Info— a pie chart showing how many images were converted successfully (Success), how many were skipped (Skip), and how many failed (Error).
• Converted By Info — a breakdown of images by generation method: Page Load, Cron or CLI Command, depending on the conversion modes you've used.
• Period / Count — the number of images converted over different timeframes: the last 5 minutes, hour, day and 7 days. Use this to confirm AVIF image conversion is actively running.
• Total Image Sizes — a comparison of your Original image size, the Original (Processed) size (originals that have already been scanned), the converted AVIF size, and the Diff — the total disk space you've saved by switching to AVIF images.

Scanning and converting images

Two buttons in the top-right corner let you manage the conversion manually, in addition to whatever AVIF Generation Mode you've configured:

• Scan — searches your media and static folders for images that haven't been processed yet and adds them to the grid. The conversion will be executed during the next cron or the Optimize action.
• Optimize — converts the images currently found by the scan into AVIF format.

bin/magento magefan:image-converter:scan

bin/magento magefan:image-converter:convert

Using the grid

Every image the AVIF extension has found or converted is listed in the grid below, with the information on the original and AVIF image paths, original & AVIF sizes in KB, conversion percentage, status, conversion method and additional actions: delete or regenerate each image. 

Use Filters to find a specific image by path or status, or regenerate/delete images in bulk via Actions dropdown above the grid.

Troubleshooting AVIF Images

Find the most common AVIF generation-related issues that might happen and their solutions.

AVIF images are not generated

If you don't see any AVIF files being created, it's usually because the extension is disabled or the wrong generation mode is selected for your setup.

Solution:

1. Navigate to Stores > Configuration > Magefan Extensions > AVIF Images and make sure Enabled is set to Yes.
2. Check the AVIF Generation Mode — if it's set to Manually by CLI command, images won't convert until you run the CLI command. So, it's best to switch to Page Load & Cron mode.
3. If you use Cron or Page Load & Cron mode, confirm crons are configured and running:

php bin/magento cron:run

Quality changes don't apply to existing images

The extension doesn't reconvert images that were already converted to AVIF format. Thus, changing the Quality option only affects images that weren't converted yet.

Solution:

1. Update the Quality (1-100) option.
2. Run the Clean Converted Images Cache.
3. Save the settings to trigger regeneration for all images with the new quality value.

Some images are still served in the original format

This is expected behaviour, but only for browsers that don't support AVIF, or for image files skipped from AVIF conversion under Skip Media Folders or Skip Static Folders sections.

Solution:

1. Check whether the image folder or file is listed in Skip Media Folders or Skip Static Folders sections and remove it if needed.
2. Test the page in a browser that supports AVIF to confirm the fallback to original files isn't the cause.
3. If the affected file is in CSS background or a slider added via page builder, make sure the corresponding option is enabled in the Advanced AVIF Conversion Settings.