Skip to main content

Ensure images are optimized

Google PageSpeed Optimizer automatically optimizes your store images to improve load times and overall site performance. However, for the process to work correctly, it’s important to ensure your Magento cron is running and all required image optimization libraries are properly installed.

Check that cron jobs are working​

The image optimization process runs automatically through Magento’s default cron. Make sure that:

  • Cron jobs are configured on your server.
  • Cron is running without errors.
  • Magento’s cron tasks are executed regularly (usually every minute).
note

If cron is not working properly, image optimization and WebP conversion will not run automatically.

Verify required tools​

To check whether all optimization tools are installed and working correctly, run:

bin/magento mirasvit:optimize-image:validate

If you see messages about missing libraries, install them using your system package manager:

# Ubuntu
sudo apt-get install jpegoptim optipng gifsicle webp imagemagick

# CentOS
sudo yum install jpegoptim optipng gifsicle webp imagemagick

If Use AVIF images is enabled, also install avifenc. See How to serve AVIF images.

Run optimization manually​

You can manually trigger image optimization at any time by running:

bin/magento mirasvit:optimize-image:optimize
note

The command optimizes a limited number of images per iteration, so you may need to run it multiple times to process all images.

Understand which images are optimized​

The extension can use one of two optimization strategies:

StrategyDescription
FilesystemScans all images inside pub/media and optimizes them in batches.
WebpagesProcesses only images that appear on the website pages visited by users. This strategy prioritizes visible, frequently used images.
Recommendation

Use the Webpages strategy for better performance and to optimize the most relevant images first.

Why some images may not be optimized​

Some images cannot be converted to WebP or optimized because they fall under exceptions. These include:

  • Images without <img> tags or proper src attributes
  • Images with lazy-loading classes: lazyOwl, owl-lazy, swiper-lazy, mst-no-webp
  • Images loaded dynamically via AJAX
  • Images added inline in HTML (for example, as background-image in a style attribute)

Unfortunately, these images cannot be optimized automatically by the extension.

Why an image has no AVIF copy​

An image is not converted to AVIF when:

  • It is a GIF. Only JPEG and PNG images get an AVIF copy.
  • Its format is selected in Exclude image formats from optimization.
  • avifenc failed on it. The error is written to var/log/system.log, and the image is shown as WebP (or in its original format) instead. The extension tries it again when avifenc on the server is updated, when you change AVIF quality, or after a week.

Handling “Command returned non-zero exit code” errors​

During image optimization, you may sometimes encounter messages like:

Command returned non-zero exit code:

Such errors can occur for various reasons — for example, when the file extension does not match the actual file type.

When this happens, the system will display the exact command that failed, for example:

jpegoptim --all-progressive --strip-xmp --strip-com --strip-exif --strip-iptc "/path/to/pub/media/iopt/example-image.jpg" 2>&1

If you run this command manually in your terminal, you will see the specific error message and the reason for the failure. This helps identify whether the issue is caused by a corrupted image, a format mismatch, or a missing tool.

Re-run optimization if needed​

If you notice that some images are still not optimized:

  1. Run the command a few more times:

    bin/magento mirasvit:optimize-image:optimize

  2. Visit different pages on your storefront if using the Webpages strategy — this helps the extension detect more images for optimization.

  3. Verify that cron is running and no system resource limits prevent optimization tasks.

tip

If you enable Use WebP images or Use AVIF images, give Magento cron some time to process and convert your images before checking the results in PageSpeed Insights.