How to Convert WordPress Images to WebP and AVIF

To serve WebP and AVIF images on WordPress, install WebP/AVIF Images for WordPress, convert your library under Media → Image optimisation, then tick Serve to visitors. The plugin writes a WebP copy (and, if you switch it on, an AVIF copy) beside every JPEG and PNG and changes the image addresses in your pages to point at the copies. Your original files are never changed. Serving is off after installation, so no image address changes until you tick that box; the separate Load first setting is on from the start.

How the plugin serves WebP and AVIF

The plugin works on the page, not on the server. It adds no rewrite rules, does not touch .htaccess or nginx, does not read the browser’s Accept header and does not output <picture> elements. It reads the finished HTML of each front-end page and adds .webp (or .avif) to every image address that has a copy.

Because it adds no server rules, WebP needs no Apache or nginx setup. The one server check it makes is for AVIF (see Adding AVIF); it does not check how your server sends .webp files. Some things are deliberately left alone:

• Only JPEG and PNG images get copies. GIF, SVG and images that are already WebP or AVIF do not.
• Images on another host or a CDN domain, images outside the uploads folder (theme and plugin images) and images set in an external CSS file are not rewritten.
• Emails, feeds, sitemaps, the REST API and wp-admin keep their JPEGs. So do <meta> tags (Open Graph and Twitter images) and JSON-LD structured data.

What you need

• WordPress 6.5 or later and PHP 8.0 or later.
• Imagick or GD with WebP support on the server.
• For AVIF only: Imagick with AVIF or GD with imageavif(), and a web server that sends .avif files as image/avif.
• An uploads folder that PHP can write to, because copies sit beside the originals, and an Administrator account.
• WooCommerce is optional. If it is active, the product gallery and variation images are rewritten too.
• A licence key, used for updates only. This is a paid plugin, but it converts and serves images without one.

Step-by-step setup

1. Download the zip under My Account → Downloads on wpexpertshub.com. In WordPress, open Plugins → Add Plugin → Upload Plugin, choose the zip, click Install Now, then Activate.
2. Optional but recommended: open Plugins → WpExperts Hub Licences, paste your key into Licence key and click Activate licence.
3. Open Media → Image optimisation. If a red notice says the server cannot write WebP, ask your host to enable WebP in Imagick or GD.
4. Click Estimate time and disk space. It only converts a small sample into temporary files.
5. Click Convert remaining images and leave the screen open. For a large library, click Check all in the background instead.
6. Open Media → Library in list view and read the WebP column: the saving for each image, or why it could not be converted.
7. In the Settings card, tick Serve to visitors and click Save Changes. Then clear your page cache.
8. Test it: view the source of a front-end page. The addresses of converted images now end in .webp. Add ?wphub_webp=0 to the page address to see the page without the rewrite.

How conversion works

For each JPEG or PNG, the plugin converts the attached file and every size WordPress made from it that exists on disk. If WordPress scaled a large upload, the attached file is the -scaled version, and the unscaled original is skipped because WordPress itself does not put it on a page. The copy sits in the same folder with the extension added: photo-300x300.jpg gains photo-300x300.jpg.webp.

Every copy is checked as it is written, and a damaged one is deleted. New and edited images are queued when WordPress saves their metadata (the New uploads setting, on by default). The job runs about a minute later through Action Scheduler if available, otherwise WP-Cron. For the existing library, the WebP & AVIF tab has these buttons:

• Convert remaining images: converts every image with no record yet, newest first, in your browser. The button reads Pause while it runs.
• Check all images again: makes only what is missing: a size with no copy, a copy older than its file or a damaged copy. Copies that are already right are not touched.
• Check all in the background: the same check, run by the site itself, so it carries on with the screen closed. It is refused with a reason if the site cannot request its own admin-ajax.php.
• Re-convert all images: in the Re-convert every image fold-out, with a background version. After you confirm, it redoes every copy with the current settings.

For one image, use Convert to WebP or Re-convert WebP under its name in Media → Library (list view). WP-CLI can do the bulk job too:

wp wphub-webp status
wp wphub-webp convert --limit=200

Quality and copies that are not kept

• WebP quality: 40 to 95, default 80. A change applies to images converted from then on, so use Re-convert all images to redo the rest.
• Graphics: the setting “Keep PNG graphics lossless where that is no bigger” is on by default. A PNG is encoded both ways, and the lossless copy is kept when it is at most 10% larger than the lossy one. Photographs saved as PNG stay lossy, and JPEGs are always lossy.
• Kept as original: if a WebP copy is not smaller than its original, it is deleted and the original is served. The WebP column says “N kept as original (WebP was larger)”.

How the copies reach visitors

With Serve to visitors ticked, the plugin starts an output buffer on template_redirect and passes each finished page through one filter. Any address in your uploads folder that ends in .jpg, .jpeg or .png gets .webp added, but only if its copy exists on disk and passes a basic size check. An image without a copy keeps its original address, so you can switch serving on before the whole library is converted.

• Where it looks: the whole page, so src, srcset, data-* attributes, inline style backgrounds and links to image files all change.
• Which requests: ordinary front-end HTML pages only, logged-in users included. Admin, AJAX, cron, feeds, REST, XML-RPC and JSON responses are skipped.
• No browser detection: the rewrite does not look at the browser. If it fails, the original page is sent.

Browsers that cannot show WebP or AVIF

On any page where an address was changed, the plugin adds a small inline script (wphub-webp-fallback) before </head>. It listens for load errors on <img> elements. If an image showing a .avif copy fails, the script switches its src and srcset to the .webp copy. If one showing a .webp copy fails, it switches to the original. Each step removes a suffix, so it cannot loop.

Two limits follow. The browser requests the new file first and the script reacts to the failure. And a CSS background that a browser cannot show is not repaired, because only <img> elements are covered.

Adding AVIF

AVIF is off by default. Tick AVIF (Also make AVIF copies, and serve them to images on the page), save, then click Check all images again to make the copies for existing images. The checkbox is greyed out if neither Imagick nor GD can write AVIF.

• An AVIF copy (photo.jpg.avif) is kept only when it is smaller than both the original and the WebP copy. AVIF quality is 30 to 90, default 60.
• AVIF goes to <img> src and srcset and, since version 0.5.3, to the WooCommerce gallery and variation data. Links, CSS backgrounds and everything else stay WebP.
• AVIF is served only after the plugin has confirmed that your server sends .avif as image/avif. When you open the tab on a server that can write AVIF, it writes a tiny test file to the uploads folder, requests it once from your own site, deletes it and remembers the answer for 24 hours.
• If the server sends another type, AVIF copies are made but not put on pages. The screen says to add image/avif avif; to nginx’s mime.types, or AddType image/avif .avif for Apache.

Your originals, and how to undo it

Conversion only reads your originals. Only two other tools on the screen write anything, when you use them: Make missing sizes (Image sizes tab) adds size files, updates the image’s size list and never deletes old ones, and the Alt text tab saves the text you type. Deleting an image in the media library deletes its copies too. To undo the conversion:

1. Untick Serve to visitors, click Save Changes and clear your page cache. Pages return to the original addresses at once. Untick Load first as well for markup exactly as before.
2. To free disk space, open the Remove all WebP and AVIF copies fold-out at the bottom of the WebP & AVIF tab and click Remove all copies. The button is greyed out while Serve to visitors is ticked in the saved settings. wp wphub-webp purge does the same and asks you to confirm. Both remove the copies of every image the plugin has processed, and their records. Your originals stay.
3. If you activated a licence, click Deactivate licence under Plugins → WpExperts Hub Licences, then deactivate the plugin and delete it.

Do step 2 before step 3. Deleting the plugin removes its settings and records but leaves every .webp and .avif file on disk. Without the records the plugin can no longer list them, so you would delete those files by hand. Deactivating alone stops the rewrite and deletes nothing.

Good to know and troubleshooting

• Pages still show the original addresses: Serve to visitors is off (the default), a page cache holds an older page, the image has no copy or was kept as original, or its address is on another host, outside the uploads folder or in external CSS. Check the image’s WebP column.
• An image is listed under “Images that could not be converted”: the reason comes from the image library on your server. Fix the cause (a damaged file usually needs uploading again), then click Try again.
• AVIF copies exist but pages use WebP: read the message under the AVIF checkbox. The server may send the wrong type, the site may not have reached itself for the check, or that image has no AVIF copy because it was not smaller.
• A run stops and says the encoder is writing damaged files: PHP has probably run short of memory. Nothing damaged is kept. Restart PHP, then press the button again; it skips what is done.
• A replaced image still shows the old picture: the front end checks that a copy exists but not its date. Check all images again converts copies that are older than their file.
• Load first changed a page while serving is off: it is on by default and works without Serve to visitors. It adds fetchpriority="high" to the first large image and removes loading="lazy" from it, or preloads a CSS background. Untick Load first to stop it.

The full documentation covers every setting, WP-CLI command and filter, and the Image sizes and Alt text tabs.

Links

Plugin page: WebP/AVIF Images for WordPress. Settings reference: WebP/AVIF Images for WordPress documentation. More tools: Browse all plugins.