Yireo - Developer training

Open main menu
Webp 2

Magento 2 Extension

Webp 2

Serve smaller images to modern browsers like Chrome
  • 100% open source and well-written
  • compliant with modern Magento standards
  • Free with no strings attached
  • Community collaboration via GitHub

Latest release: 0.12.5

Jisse Reitsma

This extension has been created by Jisse Reitsma

This extension has been written - with love - by Jisse Reitsma, founder of Yireo, three times Magento Master, partner of ExtDN, trainer and author. Jisse has been in the Magento ecosystem for many years and has created numerous Magento extensions. He also has been pushing better coding practices, like CI/CD, clean coding, coding standards and testing.

Packages & pricing

This extension is hosted on GitHub:

Usage after installation

About this module

  • When <img> tags are found on the page, the corresponding JPG or PNG is converted into WebP and a corresponding <picture tag is used to replace the original <img> tag.
  • The Fotorama gallery of the Magento core product pages is replaced with WebP images without issues as well. However, the Fotorama effect loads new JPG images again, replacing the original <picture> tag. This shows that the Fotorama library is not scalable and may be a bad decision to use. We recommend you replace it with the Notorama module instead.

System requirements

Make sure your PHP environment supports WebP: This means that the function imagewebp should exist in PHP. We hope to add more checks for this in the extension itself soon. For now, just open up a PHP phpinfo() page and check for WebP support. Please note that installing libwebp on your system is not the same as having PHP support WebP. Check the phpinfo() file and add new PHP modules to PHP if needed. If in doubt, simple create a PHP script test.php and a line <?php echo (int)function_exists('imagewebp'); to it: A 1 indicates that the function is available, a 0 indicates that it is not. Alternatively you can check for WebP using the command php -r 'var_dump(gd_info());'. Make sure your CLI binary is the same as the one being called by the webserver though.

An alternative is that the cwebp binary from the WebP project is uploaded to your server and placed in a generic folder like /usr/local/bin. Make sure to grab a copy from this binary from the rosell-dk/webp-convert project. This method is preferred because it is the fastest. But it assumes also that the binary is placed in a folder by the server administrator.

We recommend you to work on making all options work, not just one.

Please note that both tasks should be simple for developers and system administrator, but might be magical for non-technical people. If this extension is not working out of the box for you, most likely a technical person needs to take a look at your hosting environment.

Requesting support

First check to see if our extension is doing its job

Before requesting support, please make sure that you properly check whether this extension is working or not. Do not look at your browser and definitely do not use third party SEO tools to make any conclusions. Instead, inspect the HTML source in your browser. Our extension modifies the HTML so that regular <img> tags are replaced with something similar to the following:

  <source type="image/webp" srcset="example.webp">
  <source type="image/png" srcset="example.png">
  <img src="example.png" />

If similar HTML is there, but your browser is not showing the WebP image, then realize that this is not due to our extension, but due to your browser. Unfortunately, we are not browser manufacturers and we can't change this. Refer to https://caniuse.com/#search=webp instead.

Opening an issue for this extension

Feel free to open an Issue in the GitHub project of this extension. However, do make sure to be thorough and provide as many details as you can:

  • What browser did you test this with?
  • What is your Magento version?
  • What is your PHP version?
  • Did you make sure to use composer to install all dependencies?
    • Not using composer is not supported.
  • Which specific composer version of the Yireo WebP2 extension did you install?
  • Which specific composer version of the Yireo NextGenImages extension did you install?
  • Have you tested this after flushing all caches, especially the Full Page Cache?
  • Have you tested this after disabling all caches, especially the Full Page Cache?
    • The Full Page Cache will prevent you from seeing dynamic results. The Full Page Cache works with our extension, it just pointless to troubleshoot things with FPC enabled, unless you are troubleshooting FPC itself.
  • Are you testing this in the Developer Mode or in the Production Mode?
    • We recommend you to use the Developer Mode. Do not use the Default Mode anywhere. Do not use the Production Mode to make modifications to Magento.
  • Under Stores> Configuration> Yireo> Yireo WebP2 and Stores> Configuration> Yireo> Yireo NextGenImages, what settings do you see with which values?
    • Preferably post a screenshot with the settings.
  • Could you supply a URL to a live demo?
  • Could you please supply a snapshot of the HTML source of a product page?

Please note that we do not support Windows to be used to run Magento. Magento itself is not supporting Windows either. If you are stuck with Windows, make sure to use the WSL (Windows Subsystem for Linux) and use the Linux layer instead.

If the WebP configuration section is showing in the backend, but the HTML source in the frontend is not modified, please send the output of the command bin/magento dev:di:info "\Magento\Framework\View\LayoutInterface".

Issues with specific images

If some images are converted but others are not, please supply the following details:

  • The output of the command bin/magento next-gen-images:test-uri $URL where $URL is the URL to the original image (JPG or PNG)
  • The output of the command bin/magento next-gen-images:convert $PATH where $PATH is the absolute path to the original image (JPG or PNG)
  • Whether or not you are using a CDN for serving images.

Quick Start

Get up and running with your Yireo extension

Installation via composer URL

We recommend to install Magento 2 extensions via composer. See the Composer project for instructions on how to get composer up and running. Once composer is installed, use the following command to install our extension.

composer require yireo/magento2-webp2

This will make composer download the package from Packagist. After the composer installation has finished, use the following commands to enable the module within Magento:

bin/magento module:enable Yireo_Webp2 Yireo_NextGenImages
bin/magento cache:clean
bin/magento setup:upgrade

After these commands, the extension is ready for use in Magento. If you were already logged into the Magento Admin Panel, make sure to logout and log back in again, before proceeding. Do not forget to grab yourself a manual copy of our extension as a backup.

Manual installation

Please note that we strongly recommend using composer instead. If you bump into issues with this manual procedure, the first thing we need to ask is whether you have installed all dependencies, as mentioned in the composer.json file of this extension. If the composer.json file of this extension mentions requirements, you need to fulfill these requirements. This could involve checking for PHP requirements but also installing third party add-ons. Sounds difficult? Yes! That's why we can only recommend you to use composer. The manual installation does NOT make your life easier, even if you think it does.

Do use composer: It allows for dependency tracking and in the end, prevents breaking your site. However, in some cases, it might be required to do a non-composer installation. For these exceptional situations, download the module ZIP from our site (under the tab File Downloads). Next, create a folder with the following name and copy to the ZIP contents to it:


After the files have been uploaded, confirm that all files are in place. For instance, you should have a file like app/code/Yireo/Webp2/etc/module.xml. Next, use the following commands to enable the module within Magento:

bin/magento module:enable Yireo_Webp2 Yireo_NextGenImages
bin/magento cache:clean
bin/magento setup:upgrade

After these commands, the extension is ready for use in Magento. If you were already logged into the Magento Admin Panel, make sure to logout and log back in again, before proceeding. Do not forget to grab yourself a manual copy of our extension as a backup.


Head over to the GitHub repository for downloads: https://github.com/yireo/Yireo_Webp2

Frequently Asked Questions

Yes. The people of integer_net have created a Hyvä compatibility module for our Yireo WebP2 module. This also works fine with the new architecture of Yireo NextGenImages. See the integer_net blog for more information.

No, it is not. As a policy, all our Yireo software is unencrypted - we do not make use of technologies like ionCube or ZendOptimizer. All PHP-code is open source, but for commercial extensions the code is only given to paying customers.

You probably would like to know if this extension is working under a specific Magento version 2.X.Y. However, from a technical point of view, the question is wrong: The major Magento version 2.X.Y is not semantical but instead used for marketing purposes. It doesn't give any guarantees.

Instead, we maintain compatibility with the actual modules that lie underneath (like Magento_Catalog or the Magento Framework). And version management for these dependencies is handled via composer. We strongly advice you to rely on composer to answer the question whether our extension works under a specific Magento version. This is the only way to guarantee compatibility in a professional way.

Alternatively, study our CHANGELOG for details on the progress we made.

This extension is offered for free. Feel free to go the GitHub repository (see the link under Quick Start> Downloads) and open an Issue there. Please note that this is a voluntary open source project. The more helpful you are in describing the issue at hand, the more likely volunteers can come in to help you with the issue.

Make sure to test things with the obvious caches disabled (Full Page Cache, Block HTML Cache). Once this extension is working, catalog images (like on a category page) should be replaced with: Their <img> tag should be replaced with a <picture> tag that lists both the old image and the new WebP image. If the conversion from the old image to WebP goes well.

You can expect the HTML to be changed, so inspecting the HTML source gives a good impression. You can also use the Error Console to inspect network traffic: If some webp images are flying be in a default Magento environment, this usually proofs that the extension is working to some extent.

Yes, it is normal. This extension does two things: It shows a WebP on the frontend of your shop. And it generates that WebP when it is missing. Obviously, generating an image takes up system resources. And if you have a large catalog, it is going to do more time. How much time? Do make sure to calculate this yourself: Take an image, resize it using the cwebp binary and measure the time - multiply it by how many images there are. This should give a fair estimation on how much time is needed.

Note that this extension allows for using various mechanisms (aka convertors). Tune the Convertors settings if you want to try to optimize things. Sometimes, GD is faster than cwebp. Sometimes, GD just breaks things. It depends, so you need to pick upon the responsibility to try this in your specific environment.

Also note that this extension allows for setting an encoding. The default is auto which creates both a lossy and a lossless WebP and then picks the smallest one. Things could be twice as fast by setting this to lossy.

If you don't like the generation of images at all, you could also use other CLI tools instead.

We only support the installation of our Magento 2 extensions, if they are installed via composer. Please note that - as we see it - composer is the only way for managing Magento depedencies. If you want to install the extension manually in app/code, please study the contents of cmoposer.json to install all dependencies of this module manually as well.

This could mean that the conversion failed. New WebP images are stored in the same path as the original path (somewhere in pub/) which means that all folders need to be writable by the webserver. Specifically, if your deployment is based on artifacts, this could be an issue.

Also make sure that your PHP environment is capable of WebP: The function imagewebp should exist in PHP and we recommend a cwebp binary to be placed in /usr/local/bin/.

Last but not least, WebP images only work in WebP-capable browsers. The extension detects the browser support. Make sure to test this in Chrome first, which natively supports WebP.

If you are seeing this issue in the exception.log and/or system.log, do make sure to wipe out Magento caching and do make sure that the WebP file in question is accessible: The webserver running Magento should have read access to the file. Likewise, if you want this extension to automatically convert a JPEG into WebP, do make sure that the folder containing the JPEG is writable.

Not all JPEG and PNG images are fit for conversion to WebP. In the past, WebP has had issues with alpha-transparency and partial transparency. If the WebP image can't be generated by our extension, it is not generated. Simple as that. If some images are converted but some are not, try to upload those to online conversion tools to see if they work.

Make sure your cwebp binary and PHP environment are up-to-date.

Don't complain to us. Instead, ask the other browser vendors to support this as well. And don't say this is not worth implementing, because I bet more than 25% of your sites visitors will benefit from WebP. Not offering this to them, is wasting additional bandwidth.

It could be that your transactional email templates are including XML layout handles that suddenly introduce this extensions functionality, while actually adding WebP to emails is a bad idea (because most email clients will not support anything of the like).

If you encounter such an email, find out which XML layout handle is the cause of this ({handle layout="foobar"}). Next, create a new XML layout file with that name (foobar.xml) and call the webp_skip handle from it (<update handle="webp_skip" />). So this instructs the WebP extension to skip loading itself.

Ask your system administrator to install this library. Or ask the system administrator to install WebP support in PHP by upgrading PHP itself to the right version and to include the right PHP modules (like imagemagick). Or skip converting WebP images by disabling the setting in our extension and then convert all WebP images by hand.

Yes, you can. Make sure to install the addition https://github.com/yireo/Yireo_Webp2ForAmastyShopby as well.


Getting support

If you run into problems, we are happy to help you out with the following resources:

  • Check FAQ on this page
  • See our Quick Start on this page
  • Open an Issue in the GitHub repository
    • Be as descriptive in your issue as possible
    • Do everything you can to troubleshoot the issue yourself
    • Understand that you are asking others to give up their free time

We usually respond in 24 hours but understand this is all done on a voluntary basis. Also note that we require you to collaborate together with us. Interpret errors as best as you can, before claiming our time. Free software does not automatically lead into free support as well.


This extension ships with Integration Tests (Test/Integration/) and a Travis CI build (.travis.yml which triggers scripts in .ci-scripts/). The CI scripts can be tested locally with the Dockerfile:

docker build -t ci .
docker-compose up --build --abort-on-container-exit

Supported Magento versions

  • 2.2 (2.2.5, 2.2.6, 2.2.7, 2.2.8, 2.2.9, 2.2.10)
  • 2.3 (2.3.2, 2.3.3, 2.3.4, 2.3.5, 2.3.5-p1, 2.3.5-p2, 2.3.6, 2.3.7, 2.3.7-p1, 2.3.7-p2)
  • 2.4 (2.4.0, 2.4.1, 2.4.2, 2.4.2-p1, 2.4.2-p2, 2.4.3, 2.4.4, 2.4.5)
The supported PHP versions equal the versions supported by Magento itself

Requirement details

  • yireo/magento2-next-gen-images: ~0.3
  • magento/framework: ^101.0.1|^101.1|^102.0|^103.0
  • magento/module-backend: ^100.0|^101.0|^102.0
  • magento/module-config: ^101.0.0|^101.1.0
  • magento/module-page-cache: ^100.0
  • rosell-dk/webp-convert: ^2.0
  • psr/log: ^1.0
  • php: >=7.1.0
  • ext-json: *
  • ext-pcre: *
  • ext-gd: *


All notable changes to this project will be documented in this file.

The format is based on Keep a Changelog, and this project adheres to Semantic Versioning.


[0.12.5] - 19 March 2023

  • Version bump because of new NextGenImages minor

[0.12.4] - 13 September 2022

  • Implement the NextGenImages config setting convert_images

[0.12.3] - 20 August 2022

  • Add missing semicolon #130

[0.12.2] - 21 July 2022

  • Using JS native _determineProductData function #120 (@artbambou)
  • Fix uncaught exception #127 (@jakegore)

[0.12.1] - 2 June 2022

  • Skip image replacement if target URL is still empty

[0.12.0] - 4 May 2022

  • Added ACL for user permissions (@jeroenalewijns)
  • Always add webp CSS class to body via JS detection
  • Add various integration tests
  • Refactoring because of changed NextGenImages API
  • Moved AJAX plugin for swatches to NextGenImages

[0.11.4] - 23 August 2021

  • Check for double InvalidInputImageTypeException

[0.11.3] - 23 August 2021

  • Fix wrong exception being caught

[0.11.2] - 11 August 2021

  • Remove async from function (IE11 Support) (@barryvdh)

[0.11.1] - 10 August 2021

  • Fix error to config.xml introduced in last version (@chrisastley)

[0.11.0] - 9 August 2021

  • New option encoding for better performance with only lossy (@basvanpoppel)

[0.10.11] - 15 July 2021

  • Prevent exception when GIF is renamed to JPG

[0.10.10] - 7 July 2021

  • Hide all other fields if setting "Enabled" is set to 0
  • Add current store to all methods

[0.10.9] - 24 June 2021

  • Fix PHP Notice when gallery is missing

[0.10.8] - 24 June 2021

  • Allow configuring convertors (#77)

[0.10.7] - 6 May 2021

  • Prevents error if variable $imageData[$imageType] is empty (@maksymcherevko)

[0.10.6] - 2 April 2021

  • Webp images not being generated if cached jpg does not exist yet #70 (@gtlt)

[0.10.5] - 9 March 2021

  • Refactor conversion errors
  • Move helper function to NextGenImages
  • Throw exception when no conversion is needed
  • Update convertor class to comply to updated interface

[0.10.4] - 15 February 2021

  • Log all exceptions to NextGenImages logger

[0.10.3] - 12 February 2021

  • Make sure configurable images don't throw exception

[0.10.2] - 12 February 2021

  • Make sure wrong gallery images don't throw exception

[0.10.1] - 11 February 2021

  • Fix JS error
  • Rewrite into synchronous way of detecting WebP

[0.10.0] - 28 January 2021

  • Improved support on product detail page (configurable swatches + fotorama)

[0.9.6] - 22 January 2021

  • When no .webp file is available, the source tag will be removed to prevent old image being shown on the frontend (@ar-vie)

[0.9.5] - 3 December 2020

  • Remove class UrlReplacer again after refactoring NextGenImages

[0.9.4] - 3 December 2020

  • Fix missing class UrlReplacer

[0.9.3] - 2 December 2020

  • Fix composer deps with magento2-next-gen-images

[0.9.2] - 30 November 2020

  • Stick to new ConvertorInterface interface of NextGenImages

[0.9.1] - 30 November 2020

  • Wrong composer dependency with NextGenImages

[0.9.0] - 30 November 2020

  • Remove JavaScript check and Browser class
  • Moved code from this module to generic NextGenImages module
  • Remove Travis CI script

[0.8.0] - 30 November 2020

  • Lazy loading configuration option was not working
  • Add new option for quality level

[0.7.6] - 19 August 2020

  • Fixes wrong name in require-js config (@johannessmit)

[0.7.5] - 13 August 2020

  • Add jQuery Cookie to prevent load order issues (@basvanpoppel)

[0.7.4] - 3 August 2020

  • Image is correctly updated including the source (@johannessmit)
  • Undo of parse_url Laminas replacement because this breaks pre-Laminas Magento releases

[0.7.3] - 29 July 2020

  • Magento 2.4 support
  • Numerous PHPCS issues
  • URL parsing via laminas/laminas-uri package

[0.7.2] - June 13th, 2020

  • Remove alt attribute from picture element (@gjportegies)

[0.7.1] - April 6th, 2020

  • Quick fix to allow for WebP images in catalog swatches

[0.7.0] - March 31st, 2020

  • Code refactoring to allow for Amasty Shopby compatibility

[0.6.2] - March 18th, 2020

  • Skip captcha images (PR from @jasperzeinstra)

[0.6.1] - March 18th, 2020

  • Do not throw error in debugging with non-existing images
  • Rename "Debug Log" to "Debugging" because that's what's happening

[0.6.0] - March 7th, 2020

  • Skipping WebP image creation by configuration option

[0.5.2] - March 5th, 2020

  • Fix next tag not being closed properly

[0.5.1] - February 19th, 2020

  • Prevent overwriting existing picture tags

[0.5.0] - February 11th, 2020

  • Upgraded rosell-dk/webp-convert library

[0.4.7] - January 31st, 2020

  • Add class attribute in picture (PR from itsazzad)
  • Better support info
  • Raise framework requirements for proper support of ViewModels
  • Added logic for fetching the css class from the original image (PR from duckchip)
  • Added missing variable in the ReplaceTags plugin (PR from duckchip)

[0.4.6] - November 23rd, 2019

  • Raise requirements for proper support of ViewModels

[0.4.5] - October 16th, 2019

  • Add check for additional layout handle webp_skip

[0.4.4] - October 15th, 2019

  • Dirty workaround for email layout

[0.4.3] - October 4th, 2019

  • Add controller for email testing
  • Do not apply WebP if no handles

[0.4.2] - July 14th, 2019

  • Make sure modified gallery images are returned as Collection, not an array
  • Test with Aimes_Notorama

[0.4.1] - July 2019

  • Original tag (with custom styling) was not used in picture element, but new one was created instead

[0.4.0] - July 2019

  • Move configuration to separate Yireo section
  • Add a config.xml file
  • Changed configuration path from system/yireo_webp2/* to yireo_webp2/settings/*
  • Move quality_level to config.xml

[0.3.0] - 2019-05-02

  • Fix issue with additional images not being converted if already converted (@jove4015)
  • Fix issue with static versioning not being reckognized
  • Make sure src, width and height still remain in picture-tag
  • Integration test for multiple instances of same image
  • Add fields in backend for PHP version and module version
  • Integration Test to test conversion of test-files
  • Throw an exception of source file is not found
  • Add provider of dummy images
  • Add integration test of dummy images page
  • Add test page with dummy images
  • Only show original image in HTML source when debugging

[0.2.0] - 2019-04-28

  • Fix issue with additional images not being converted if already converted
  • Make sure to enable cookie-check whenever FPC is enabled
  • Actual meaningful integration test for browsing product page

[0.1.1] - 2019-04-12

  • Disable gallery fix if FPC is enabled

[0.1.0] - 2019-04-12

  • Add GD checker in backend settings

[0.0.3] - 2019-03-21

  • Fix for Fotorama gallery
  • Check via timestamps for new and modified files
  • Check for browser support via cookie and Chrome-check
  • Inspect ACCEPT header for image/webp support
  • Implement detect.js script to detect WebP support and set a cookie
  • Add configuration values

[0.0.2] - 2019-03-20

  • Temporary release for CI purpose

[0.0.1] - 2019-03-20

  • Initial commit
  • Support for regular img-tags to picture-tags conversion

We are a proud member of ExtDN

ExtDN forms a network of Magento extension developers, that strive for a better extension quality - both on a technical level and from an end-users point of view. With industry leaders like Fooman and aHeadworks, ExtDN lifts up the Magento extension space to a new level. And Yireo is proud to be part of this.

Do not miss out on what we say

This will be the most interesting spam you've ever read

We don't write too commercial stuff, we focus on the technology (which we love) and we regularly come up with innovative solutions. Via our newsletter, you can keep yourself up to date on all of this coolness. Subscribing only takes seconds.

Sign up for the Yireo newsletter



GitHub organizations

Legal information

Other Yireo sites

Get Social

About Yireo