WebP/AVIF Images for WordPress

1. Overview

WebP/AVIF Images for WordPress writes a smaller copy of every JPEG and PNG image in your Media Library, next to the original file. For the file and for every size WordPress made from it, photo-300x300.jpg gains a neighbour called photo-300x300.jpg.webp. When you switch serving on, the plugin reads the finished HTML of each front-end page and adds .webp to the image addresses that have a copy. Visitors download the smaller file; your originals, your Media Library and every address stored in your posts stay exactly as they were.

It works on the finished page rather than through server rules, so it needs no .htaccess or nginx change and works with any theme. It uses the image library WordPress already uses on your server (Imagick or GD). There are no binaries to install and no external conversion service: images are converted on your own server and are never sent anywhere.

The same screen also covers three related jobs. It can load the first large image of each page before everything else, make image sizes that the current theme expects and an image does not have, and list every image that has no alternative text so you can write it.

How it works

1. Copies are written. New and edited images convert in the background about a minute after they arrive. For existing images you press a button on Media → Image optimisation, or run wp wphub-webp convert.
2. Every copy is checked as it is written. A copy that is not a complete image is deleted and the reason recorded. A copy that comes out the same size as the original or larger is deleted too, and the original is kept.
3. Pages are rewritten (only if you tick Serve to visitors). On each front-end page, any address in your uploads folder that ends in .jpg, .jpeg or .png and has a usable copy gets .webp added. The page cache of your caching plugin stores the rewritten page.
4. A small script protects visitors. If a browser fails to show a rewritten image, the script on the page switches that image back (AVIF to WebP, WebP to the original).

At a glance

What it does not do

• It does not change, replace or delete your original images, and it does not change any URL stored in a post, option or the Media Library. The exceptions are the Image sizes tool, which adds new size files and updates the size list of the images it fixes (see Image sizes), and the Alt text tab, which saves the alternative text you type on that image (see Alt text). Old size files are never deleted.
• It does not convert GIF, SVG, WebP or AVIF originals. Only image/jpeg and image/png attachments get copies.
• It does not rewrite images served from another host or a CDN domain, images outside the uploads folder (theme and plugin images), or images that are set in an external CSS file. Images set in an inline style attribute are rewritten.
• It does not rewrite emails, RSS feeds, sitemaps, the REST API, wp-admin, <meta> tags (Open Graph and Twitter images) or JSON-LD structured data. Those keep the original URLs.
• It does not write alternative text for you.
• It does not add shortcodes, blocks, REST routes, widgets or database tables, and it sets no cookies.

2. Requirements

3. Installation

1. Download the plugin zip from your account on wpexpertshub.com.
2. In WordPress open Plugins → Add New → Upload Plugin, choose the zip and click Install Now. You can also upload the wphub-webp folder to /wp-content/plugins/.
3. Click Activate. A Settings link and a Licence link appear under the plugin name on the Plugins screen.
4. Open Media → Image optimisation to convert your existing library. New uploads convert automatically.
5. Optional but recommended: activate your licence to receive updates (see below).

What activation creates

Nothing. There is no activation hook, so activating creates no tables, no options, no cron events, no roles and no pages. The settings option wphub_webp_settings is written the first time you save the settings. Until then the plugin uses its defaults (see Settings). The plugin adds the menu item Media → Image optimisation, which only users with the manage_options capability can open.

Licence activation and updates

The plugin bundles the WpExperts Hub licence and update client. The plugin works as soon as it is activated. In the plugin's code, no feature checks the licence. The licence key only matters for updates: the update package link comes from the licence server, and without an active licence the Plugins screen shows Automatic update is unavailable for this plugin. Activate your licence to enable updates. under an available update.

1. Open Plugins → WpExperts Hub Licences. The same screen opens from the Licence link under the plugin name, and from the Manage licences link in the notice on the Plugins screen. The screen needs the manage_options capability and lists every WpExperts Hub plugin active on the site.
2. Paste the key from your purchase email (it is also shown under My Account → Downloads on wpexpertshub.com) into the box labelled Licence key and click Activate licence. Characters other than letters, digits and hyphens are removed from the key before it is sent.
3. The card for the plugin then shows Active and the key with the middle masked, with a Deactivate licence button. New versions appear on Dashboard → Updates and on the Plugins screen and install like any other plugin update.

• Can't find your key? Email it to me. Open this fold-out on the licence screen, enter the email address used for the purchase and click Send licence key. It asks wpexpertshub.com to email the key. The message you see comes from the server.
• Moving to another site. The screen says: Deactivate before moving the plugin to another live site. Click Deactivate licence. The licence is removed from this site even when the licence server cannot be reached; the screen then shows Licence removed from this site.
• If the server reports the licence as no longer active on this site, the card changes to Not active at the next update check. The key stays stored, so you can activate it again.
• Update information is cached for 12 hours (one batched request for all WpExperts Hub plugins on the site). If the licence server cannot be reached or answers badly, the previous information is kept and the plugin tries again after one hour. The cache is cleared after any plugin update and after you activate, deactivate or request a key.
• When the client loads. Only in wp-admin, during WP-Cron runs and under WP-CLI. Front-end requests do not load it.

What is sent to wpexpertshub.com, and when, is listed under Privacy and data.

Updating

With an active licence, update from Dashboard → Updates or the Plugins screen. Without one, upload the new zip under Plugins → Add New → Upload Plugin and choose to replace the current version. Either way your settings, the records in the database and the copies on disk are kept. After an update, existing copies stay valid; to redo copies with new settings use Re-convert (see The WebP and AVIF tab).

Multisite

The plugin has no multisite-specific code. Settings, records and the licence key are stored per site, and the copies sit in each site's own uploads folder. The update cache is a site transient, so it is shared by the network. uninstall.php does not loop over the sites of a network: on multisite, deleting the plugin clears the settings and records only for the site where the uninstall runs (see Deactivation and uninstall).

4. Quick start

1. Activate the plugin and open Media → Image optimisation. Check that no red notice says the server cannot write WebP.
2. Click Estimate time and disk space to see roughly how long the conversion will take and how much smaller the copies will be. This converts a small sample into temporary files and writes nothing beside your originals.
3. Click Convert remaining images and leave the screen open. For a large library click Check all in the background instead, which carries on with the screen closed.
4. Look at a few images in Media → Library (list view). The WebP column shows the saving for each image or the reason it could not be converted.
5. Tick Serve to visitors under Settings on the same screen and click Save Changes.
6. Clear any page cache. Open a page and view its source: image addresses now end in .webp. Add ?wphub_webp=0 to the page address to compare with the original page.

5. Features

How copies are made

For each attachment whose type is image/jpeg or image/png, the plugin lists the files that should have a copy:

• the attached file, which is the -scaled version when WordPress scaled a large upload (in WordPress 7.1.2 core scales images whose width or height is above 2,560 pixels by default, through the big_image_size_threshold filter), and
• every size listed in the image's metadata whose file exists on disk.

The pre-scaled original that WordPress keeps is left out: WordPress never puts it on a page, so a copy would only cost disk space.

Each file is converted in this order:

1. Files are handled smallest first.
2. A copy from an earlier run that is damaged is deleted before anything else, so it can never be served.
3. If the file already has a current copy (the copy exists, is at least as new as the file and passes the check), it is left alone. If an earlier run found the copy larger than the original and the file has not changed since, it is skipped. Otherwise the file is encoded.
4. The WebP copy is written to file.ext.webp beside the original, with Imagick or else GD directly. With Imagick the image is turned upright according to its orientation, CMYK images are converted to sRGB, the colour profile is kept and other metadata (EXIF and similar) is dropped. For the lossy WebP copy only: if both direct encoders fail, WordPress's own image editor is tried, and after it WordPress's GD editor.
5. The copy is checked (see below). A copy that fails is deleted.
6. If the copy is not smaller than the original, it is deleted and the file is remembered as kept as original. The plugin does not try that file again unless the file changes (its modification time is recorded) or you use Re-convert.
7. If AVIF is on, the AVIF copy is made the same way and compared with the better of the original and the WebP copy (see AVIF copies).
8. The outcome is stored on the attachment as the post meta _wphub_webp (counts, bytes, files kept as original, errors).

One conversion of an image may run for up to 120 seconds on hosts that allow the plugin to raise the PHP time limit.

Quality, lossless graphics and the size check

Lossy WebP copies use the WebP quality setting (40 to 95, default 80). The plugin writes copies with Imagick or GD directly because WordPress's image editor ignored the quality value when changing format. A change to the setting applies to images converted from then on; use Re-convert to redo existing copies.

With Keep PNG graphics lossless on (the default), every PNG is also encoded lossless. The lossless copy replaces the lossy one when it is at most 10% larger than the lossy copy (the filter wphub_webp_lossless_allowance, default 1.1, changes that). Logos, icons and flat artwork usually pass this test and stay pixel-sharp with exact transparency; photographs saved as PNG do not, and stay lossy. JPEG files are always lossy. Within one attachment the smallest size is tried first, and if lossless loses there, the larger sizes of that attachment are not tried lossless, which keeps a photographic PNG as quick to convert as a JPEG.

Every WebP or AVIF file is checked the moment it is written, and a file that fails is deleted and never counted or served:

• It must be at least 32 bytes.
• A WebP must be a RIFF/WEBP file whose declared length matches the file size, with a VP8 , VP8L or VP8X chunk, and PHP's own image reader must read it with a width and height above zero.
• An AVIF must start with a file-type box naming the avif or avis brand, its boxes must run exactly to the end of the file with a meta and an mdat box among them, and PHP's image reader must recognise it as AVIF where PHP can (PHP 8.1 and later).

This check was added after a long bulk run on a development site produced thousands of 16-byte AVIF files when the PHP process had grown very large. A damaged file recorded this way shows the reason: The encoder wrote a damaged WEBP file (N bytes), so it was not kept. This usually means the PHP process ran short of memory during a long run; a later check makes it again.

Automatic conversion of new and edited images

With New uploads ticked (the default), the plugin queues a conversion whenever WordPress saves attachment metadata for a JPEG or PNG: on upload, after an image is edited, when sizes are regenerated, and when another plugin updates the metadata. It hooks wp_generate_attachment_metadata and wp_update_attachment_metadata at priority 99 and returns the metadata unchanged.

• Delayed by a minute. WordPress writes an upload's sizes one at a time and saves the metadata after each, so an immediate job could convert only the sizes already on disk. The job runs 60 seconds later (the filter wphub_webp_queue_delay changes the delay, in seconds) and reads the file list when it runs.
• One pending job per image. If a job for the same image is already waiting, no second one is added. A job that is already running does not count, so a second job queues behind it. Converting is safe to repeat, so the second one only fills what the first missed.
• Action Scheduler or WP-Cron. If Action Scheduler is available (WooCommerce bundles it) the job is a single action of the hook wphub_webp_convert in the group wphub-webp. Otherwise it is a single WP-Cron event of the same hook. Both carry the attachment ID as the only argument.
• Not forced. A copy already newer than its file is left alone. A file that WordPress regenerated is newer than its copy, so it is converted again.
• Deleting an image deletes its copies too (hooked on delete_attachment, while the metadata still lists the sizes).

With the setting off, new images are not converted automatically. They show Not converted yet in the Media Library until you run a conversion yourself. Switching it off does not remove anything that already exists.

The Image optimisation screen

Open Media → Image optimisation. The screen needs the manage_options capability. For other users WordPress hides the menu item and refuses a direct visit to the address with its own message, Sorry, you are not allowed to access this page. (in WordPress 7.1.2 this check is in wp-admin/includes/menu.php, and it runs before the plugin's own You cannot do that. check is reached). It has three tabs: WebP & AVIF (the default), Image sizes and Alt text. A Settings link under the plugin name on the Plugins screen opens it.

The WebP and AVIF tab

Status

Four tiles summarise the library. Figures refresh while a run is going.

A progress bar shows percentage, count and an estimate of the time left. It only moves forward within a run.

Buttons

A run in the browser pauses when you click the same button again (it then reads Pause while running). Click it again to carry on from where it stopped. Convert, Check and Re-convert work in parallel lanes (three by default, see wphub_webp_parallel); each lane takes only the images whose ID falls in its share, so two lanes never work on the same image. Each request works for about five seconds (the filter wphub_webp_batch_seconds, clamped to 1 to 25).

Under the buttons the screen says how many images are waiting for the background job (N images are waiting for that now.), that every image has been through the converter when none is left (which is why Convert remaining images is greyed out), and what Check all images again does.

Background runs

A background run is a chain of short requests that the site makes to its own admin-ajax.php (action wphub_webp_bg). No request depends on a visitor or on your browser.

1. Starting a run sends one test request to the site itself and waits up to 15 seconds for the expected answer. If the site cannot reach itself, the run is refused with a reason (see Troubleshooting).
2. The work is split into lanes by attachment ID (ID % lanes). Each lane runs a step of about 20 seconds (the filter wphub_webp_background_seconds, clamped to 5 to 45), records where it got to, sends a request for its own next step and returns.
3. The request carries a random token stored with the run, not a login cookie. A request with the wrong or no token gets HTTP 403.
4. A watchdog restarts a lane that has gone quiet. It runs on WP-Cron every minute and on every status check the screen makes while it is open, so an open screen alone keeps a run alive. A lane with no step running that has not reported for 25 seconds is sent another request. A step whose lock is older than 120 seconds is treated as dead and taken over.
5. If the encoder writes damaged files three steps in a row, that lane stops and the screen says why. Restart PHP (or wait for the host to recycle it) and start the check again.
6. When you come back to the screen, a run in progress is shown with its progress, and the bar updates every five seconds. A finished run's summary stays on the screen until you start another run (the Stop button only shows while a run is active).

Images that could not be converted

When the Could not convert count is above zero, a table lists up to 25 images with the file name and the reason recorded. The reason comes from the image library on your server (shortened to 240 characters); a damaged file usually needs uploading again. Try again re-converts that image with the force option. AVIF problems are shown in the Media Library column, but do not add to the Could not convert count.

Serving copies to visitors

Tick Serve to visitors (off by default) and save. The plugin then passes the finished HTML of each front-end page through one filter. It starts an output buffer on template_redirect at the latest possible priority, so a plugin that answers the request itself and exits (a sitemap, a redirect) has already done so.

Which requests are rewritten

Only ordinary front-end HTML pages: not wp-admin, AJAX, cron, feeds, robots.txt, trackbacks, embeds, REST requests, XML-RPC or any JSON request, and not any response whose Content-Type header, if one has been set by then, is not text/html. The page must contain an <html tag. It applies to logged-in users as well as visitors. The filter wphub_webp_rewrite_enabled can switch the whole pass off for a request, and adding ?wphub_webp=0 to any page address shows that page without the rewrite and without Load first, so you can compare.

What is rewritten

Any address on your site's uploads URL (as WordPress reports it, for example https://example.com/wp-content/uploads/2026/09/a.jpg) that ends in .jpg, .jpeg or .png, in any case, and whose copy exists gets .webp added. This applies to:

• absolute and protocol-relative addresses (https://… and //…),
• root-relative addresses (/wp-content/uploads/…), only where an address can start (after a quote, an opening parenthesis, a space, a comma, an equals sign or a semicolon), so a path inside another site's address is not touched,
• addresses in src, srcset, data-* attributes and inline style="background-image:…", and
• JSON-escaped addresses such as https:\/\/example.com\/wp-content\/uploads\/a.jpg, which is how WooCommerce prints the variation images.

Only images that already have a usable copy are switched. Nothing else in the markup changes, so theme CSS is not affected. A copy counts as usable when it exists and is at least 32 bytes (for AVIF: it also starts with an AVIF file-type box). The front end does not compare dates, so a copy that is older than a replaced original is served until it is converted again; "Check all images again" converts copies older than their file. A path containing .. is never followed.

What keeps its original address

Before the rewrite, every <meta> tag and every application/ld+json script block is set aside and put back afterwards. Open Graph and Twitter images and structured data therefore keep the JPEG or PNG address: some social platforms still refuse WebP, and product feeds read the structured data. Emails, feeds, sitemaps, the REST API and wp-admin never pass through the buffer at all.

The fallback script

When at least one address on a page was changed, a small inline script (<script id="wphub-webp-fallback">) is added just before </head>. It listens for image load errors. When an <img> fails and its current source contains .jpg.avif, .jpeg.avif or .png.avif, it switches that image's src and srcset to the .webp copy. When the source contains .jpg.webp, .jpeg.webp or .png.webp, it switches to the original. Each step removes a suffix, so it cannot loop, and it works on images that a gallery swaps to a new photo later. It covers <img> elements only: a CSS background that a browser cannot show is not repaired.

Safety

If the rewrite fails for any reason (a regular expression error or an exception), the original page is sent unchanged. Turn Serve to visitors off, or deactivate the plugin, and pages return to the original addresses. Clear any page cache after you change this setting, because cached pages hold the rewritten addresses.

AVIF copies

Tick AVIF (off by default) to make a second copy, file.ext.avif, beside the WebP copy. AVIF is usually smaller than WebP but slower to make.

• Server support. The checkbox is greyed out and the screen says This server cannot write AVIF images (neither Imagick nor GD supports it). if WordPress's image editor cannot write image/avif.
• Kept only when worthwhile. An AVIF copy is kept only if it is smaller than the original and smaller than the WebP copy (when there is one). Otherwise it is deleted and remembered, like a WebP that came out larger.
• Quality. The AVIF quality setting, 30 to 90, default 60. The encoder speed is 8 on a scale of 0 (slowest, smallest) to 10 (the filter wphub_webp_avif_speed; Imagick uses at most 9).
• Where it is served. AVIF goes to <img> src and srcset, and since 0.5.3 also to the WooCommerce gallery's data-src, data-large_image and data-thumb attributes and to the data-product_variations data. Anchor links, CSS backgrounds and everything else stay WebP. The filter wphub_webp_avif_scripted (default true) turns off the gallery part.
• The web server check. Many servers still send .avif as application/octet-stream. Chrome shows such an image anyway, but Safari and others may not. So AVIF copies are put on pages only after the plugin has confirmed the type. When the Image optimisation screen opens and AVIF is supported, the plugin writes an 8 by 8 pixel AVIF file named wphub-webp-check-<random>.avif into the uploads folder, requests it once with a HEAD request to your own site (5 second timeout, certificate not verified because the request goes to the same site), deletes it, and stores the answer in the option wphub_webp_avif_mime with the time. The answer is reused for 24 hours. Only an HTTP 200 answer counts; a content type starting with image/avif is ok, any other is bad, and no answer is unknown.

The screen reports the result under the AVIF checkbox:

The check only runs when the WebP and AVIF tab is opened, and it asks again only when the stored answer is older than 24 hours. After fixing the server, open the tab again after a day, or delete the option wphub_webp_avif_mime to force a fresh check. The filter wphub_webp_serve_avif can override the verdict. After switching AVIF on, press Check all images again to make the AVIF copies for existing images.

Load first

With Load first ticked (the default), the plugin marks the first large image of each page so browsers fetch it before anything else. This runs on the same page pass as serving and works even while Serve to visitors is off. If both settings are off, the plugin does not touch the page at all. The filter wphub_webp_priority_enabled can turn it off for a request.

The plugin works from the finished HTML. Starting at the <body> tag it looks for the first image that qualifies:

• Content inside <noscript> is ignored, because it is not what renders.
• An <img> counts when it is at least 300 by 150 pixels by its width and height attributes (a missing attribute is not compared), or has a srcset and no stated size. Logos, icons and emoji (class emoji), SVG files and images with a data: source do not count. The filters wphub_webp_priority_min_width (300) and wphub_webp_priority_min_height (150) change the thresholds.
• If the first candidate has a data: placeholder source and a width of at least 300, or has data-src or data-srcset (a lazy-loading script will swap it), the plugin does nothing for the page, because choosing a later image would be a guess.
• An element counts when its inline style gives it a background picture (jpg, jpeg, png, webp, avif or gif), unless the file is shipped by WordPress or a plugin (the address contains /wp-includes/, /wp-admin/, /plugins/ or /mu-plugins/), or the style gives it a width below 300 pixels or a height below 150 pixels.

For an <img> the plugin removes loading="lazy" and any existing fetchpriority and adds fetchpriority="high". For a background it adds <link rel="preload" as="image" href="…" fetchpriority="high" id="wphub-webp-preload"> before </head>, because a CSS background cannot carry fetchpriority. Pages where an <img> in the body already has fetchpriority="high" (WordPress core and most themes do that on ordinary pages) are left alone.

Image sizes

WordPress makes an image's sizes once, when it is uploaded, with the sizes registered that day. After a theme switch or a change to WooCommerce image settings or Settings → Media, older images keep their old sizes: a thumbnail registered today at 400 × 400 may still be served from a 100 × 100 file, blurred. WordPress's own missing-sizes check compares only size names, so it never notices a size whose dimensions changed. The Image sizes tab compares by dimensions.

• Sizes in use now lists every size registered by the active theme and plugins (name, width, height, cropped yes or no), after WordPress's intermediate_image_sizes_advanced filter.
• Images counts JPEG, PNG and WebP attachments, which are the types this tab looks at.
• Check (changes nothing) goes through every image and counts how many need new or corrected sizes and how many files that would be. It writes nothing. The result reads, for example: Check finished: N images looked at; M need new or corrected sizes (F files to make). Nothing was changed.
• Make missing sizes makes them. An image needs a size when the size is missing from its metadata, when the file named in its metadata is not on disk, or when its recorded width or height differs by more than one pixel from what WordPress would make now. A size the original is too small for is skipped, as WordPress would skip it.

How a size is made: the old entry is taken out of the image's metadata, then WordPress's own routines (wp_update_image_subsizes) make the file from the original upload, as on upload. The new file gets its own name, because the dimensions are part of the file name. Old size files are never deleted, because older posts may still link to them. If a size cannot be made, its old metadata entry is put back. Each JPEG or PNG that gains sizes has its WebP copies made straight away, and its attachment metadata now lists the new files. This is the one place where the plugin writes to the Media Library's size data. The result reads, for example: Finished: N images looked at; M were given new sizes (F files made, with their WebP copies). Originals and old size files were left in place. Up to five error lines of the form Title: Some sizes could not be made from the original file. are added.

The same tool is available as wp wphub-webp sizes (see WP-CLI).

Media Library column and per-image actions

In the list view of Media → Library a WebP column appears after the title. Each row shows the status of that image, one line per fact:

Under the file name, a row action reads Convert to WebP for an image with no record or Re-convert WebP for one with a record (which forces its copies to be redone with the current settings). The same status and a Convert now or Re-convert link appear in a read-only WebP row of the attachment details panel, which is what the grid view uses because it has no columns. Both need permission to edit that image. After the click you return to where you were and a notice says "Title" converted: N WebP file(s) written. or, on failure, "Title": N file(s) could not be converted. The reason is shown in the WebP column; the original is served meanwhile.

Alt text

The Alt text tab lists every image in the Media Library (any image type, not only JPEG and PNG) that has no alternative text, or only blank text, newest first, 20 per page. The heading counts them (N images have no alternative text) and the count goes down as you save.

1. Each row shows a small preview, the title (linked to the attachment's edit screen), the file name and the post it was uploaded to.
2. Type a description in the box and click Save or press Enter. The text is stored as the image's alternative text (the _wp_attachment_image_alt meta) after WordPress's text sanitising. The box allows 300 characters in the browser.
3. Saving an empty box shows Type the alternative text first. and saves nothing. After a successful save the row shows Saved, the button reads Saved and the cursor moves to the next box.

The pager above and below the list reads Showing 1–20 of N, with Previous, Next, page numbers and, under the list, a Go to page box. Next carries on from the last image shown rather than from a page offset, so saving some images on a page never makes it skip images. Saving requires permission to edit that image. Nothing is filled in automatically: an image that is only decoration can go without, which is why the plugin leaves the decision to you.

When each feature arrived

From the readme's changelog:

• 0.2.0: Check all images again, a one-minute wait before converting a new upload, and files whose WebP came out larger are remembered.
• 0.3.0: the status tiles and progress bar, and batches of about five seconds.
• 0.4.0: the three tabs under Media → Image optimisation, the working quality setting, optional AVIF, lossless PNG graphics, Load first, the Image sizes tab, the Media Library column and per-image actions, the Alt text tab, and root-relative addresses.
• 0.4.1: the Alt text pager.
• 0.5.0: faster AVIF (encoder speed 8), parallel lanes, and background runs.
• 0.5.1: the check that discards damaged copies, and the action wphub_webp_written.
• 0.5.2: runs that no longer stop part-way or step backwards.
• 0.5.3: AVIF for the product gallery, the two-stage browser fallback, and licence activation under Plugins → WpExperts Hub Licences.

Command line

With WP-CLI the plugin adds wp wphub-webp status, convert, sizes and purge. They are described, with options and examples, under WP-CLI.

6. Where to find things

7. Settings

All settings are on Media → Image optimisation, in the Settings card of the WebP & AVIF tab. They are stored together in one option, wphub_webp_settings, and saved with Save Changes through the WordPress Settings API. Values outside a range are clamped to the nearest allowed value when saved. An unticked checkbox is saved as off. Until the first save, the defaults below apply.

Other settings that are not on this form: the licence key (stored by the licence client, see Reference), and the tuning filters listed under Filters.

8. Reference for developers

WP-CLI

The commands are registered under wp wphub-webp when WP-CLI is running.

wp wphub-webp status
wp wphub-webp convert --limit=200
wp wphub-webp convert --id=123 --force
wp wphub-webp sizes --dry-run
wp wphub-webp sizes --id=123
wp wphub-webp purge --yes

AJAX and admin-post actions

All AJAX calls are POST requests to admin-ajax.php. The screen's calls send the nonce for the action wphub_webp as _ajax_nonce.

Filters

// Turn Load first off on the front page.
add_filter( 'wphub_webp_priority_enabled', function ( $enabled ) {
	return is_front_page() ? false : $enabled;
} );

// Allow lossless PNG copies up to 25% bigger than the lossy ones.
add_filter( 'wphub_webp_lossless_allowance', function () {
	return 1.25;
} );

The first filter runs while the page is being output, after the main query, so conditional tags such as is_front_page() work. The second runs each time a PNG is converted.

Actions

Core hooks the plugin uses

Cron events and scheduled jobs

Options, post meta and transients

The plugin creates no database tables.

Files, constants and code

• Copies: <original path>.webp and <original path>.avif, in the same folder as the original. During a lossless attempt a temporary file <original path>.webp.lossless-tmp exists for a moment.
• AVIF check file: wphub-webp-check-<random>.avif in the uploads root, deleted straight after the check.
• Constants the plugin defines: WPHUB_WEBP_VERSION, WPHUB_WEBP_FILE, WPHUB_WEBP_PATH. Do not define them yourself.
• Constants and filters you may define for the licence client: WPXH_LICENCE_SERVER and the filters wpxh_licence_server and wpxh_licence_sslverify change the licence server address and whether its certificate is verified (verification is on unless the server host ends in .local, .test, .localhost or is localhost or 127.0.0.1).
• Layout: wphub-webp.php (loader), inc/ (settings, converter, sizes, queue, background, rewriter, CLI), admin/ (screen and Media Library), assets/ (admin script and style), licence/ (licence client), uninstall.php.
• PHP classes: the plugin's classes are final and used by its own screens and commands. They are not documented as a stable API. For example, WPHub_WebP_Converter::convert( int $id, bool $force = false ) converts one attachment and returns the counts, and WPHub_WebP_Rewriter::rewrite( string $html, ?bool $serve = null, ?bool $priority = null ) rewrites a string of HTML. Prefer the hooks above.
• The licence client defines the class once: the first WpExperts Hub plugin to load defines WPXH_Licence_Client_V2, and every plugin registers itself with it.

9. Privacy and data

The plugin stores no personal data about visitors and sets no cookies. It does not register a privacy policy text, a personal data exporter or an eraser.

What is stored

• Your settings in the option wphub_webp_settings.
• A record per image in the post meta _wphub_webp on each JPEG or PNG attachment: counts, byte totals, the names of files kept as original and the reasons for failures.
• Run state in the options wphub_webp_bg, wphub_webp_bg_lane_* and wphub_webp_bg_lock_* while a background run exists, and the web server check result in wphub_webp_avif_mime.
• The copies as .webp and .avif files in your uploads folder, next to the originals. They are public in the same way as the originals: anyone who can request an original from your web server can request its copy. The plugin applies no access control and sets no file permissions of its own.
• Licence data (if you activate a licence): the key and its status in the options _wphub-webp_licence_key and _wphub-webp_key_status, and the cache of the update check.

The page pass adds the script wphub-webp-fallback to pages and, for Load first, may add an fetchpriority attribute or a preload link. Neither collects anything.

What is sent anywhere

Images are converted on your own server and are never sent anywhere. The plugin makes two kinds of request to your own site, and requests to wpexpertshub.com for the licence only.

As with every request WordPress makes, the HTTP headers include WordPress's user agent, which contains the WordPress version and your site address. No customer, order or visitor data is sent. Front-end page requests do not load the licence client. A request to wpexpertshub.com can still happen inside a WP-Cron run, because WordPress checks for plugin updates twice a day through WP-Cron.

Deactivation and uninstall

• Deactivating stops the rewrite at once, so pages return to the original addresses. It deletes nothing: copies, records, settings and any queued or running jobs stay. The plugin has no deactivation hook.
• Deleting the plugin runs uninstall.php, which deletes the options wphub_webp_settings and wphub_webp_avif_mime and every _wphub_webp post meta row. It does not loop over the sites of a multisite network.
• It leaves behind all .webp and .avif files, because deleting thousands of files in one request can time out half way; the options wphub_webp_bg, wphub_webp_bg_lane_* and wphub_webp_bg_lock_* if a run state still exists; the licence options _wphub-webp_licence_key and _wphub-webp_key_status and the licence cache; and the key's activation on wpexpertshub.com, unless you deactivated the licence first.

10. Troubleshooting

When the server cannot write WebP or AVIF

If WordPress's image editor on your server cannot write image/webp, the WebP and AVIF tab shows a red notice: This server cannot write WebP images (neither Imagick nor GD supports it), so nothing can be converted. Ask the host to enable WebP in Imagick or GD. The buttons Convert remaining images, Check all images again, Check all in the background and both Re-convert buttons are greyed out. Ask your host to enable WebP in Imagick or GD.

If the server cannot write AVIF, the AVIF checkbox and the AVIF quality box are greyed out and the screen says This server cannot write AVIF images (neither Imagick nor GD supports it). WebP still works. A single file can still fail with This server cannot write WebP images. or File is not an image the server can read.; then the file or the library is the problem, and the reason is shown in the WebP column.

Common problems

11. FAQ

12. Changelog

0.5.3

• AVIF is now also used for the product gallery's zoom and lightbox images (data-src, data-large_image, data-thumb) and for the variation data, not only for <img> src/srcset. Anchor links and everything else stay WebP. Filter wphub_webp_avif_scripted turns it off.
• The fallback for browsers that cannot show an image now steps down in two stages (AVIF, then WebP, then the original) and works on images the gallery swaps to a new photo later; before, it acted once per image element.

0.5.2

• Background and on-screen runs no longer stop part-way or step backwards. The "next step" request is now delivered reliably (it used a 0.01 second timeout that a TLS handshake outlasts, so lanes silently stopped until the watchdog restarted them). A lane that has lost its next step is restarted within 25 seconds instead of 2 minutes.
• Two steps can no longer both own a lane: the lock is atomic, a step that outlives it writes nothing back, and progress is added to the lane record under the lock. Previously a late step overwrote newer counts and the percentage dropped (for example from 50% to 35%).
• The progress bar only moves forward within a run, because lanes report in whatever order their requests finish.

0.5.1

• Damaged copies are never kept, counted or served. Every WebP and AVIF is checked as it is written (headers, length, and PHP's own image reader); a damaged one is deleted and the reason recorded. Seen on a long bulk run: once the PHP process had grown very large, the AVIF encoder wrote 16-byte files without reporting an error, and 0.5.0 and earlier kept them.
• "Check all images again" now finds damaged copies from earlier runs, removes them and makes them again.
• The front end only points a page at a copy that passes the same check.
• A run stops, with an explanation, when the encoder writes damaged files several images in a row, instead of failing through the whole library. Restart PHP (or wait for the host to recycle it) and press the button again.
• New action wphub_webp_written (file, kind), fired after a copy is written and before it is checked.

0.5.0

• AVIF is made about 2.5 times faster: the encoder runs at speed 8 instead of 6 (measured: identical file sizes with Imagick, about 5% larger with GD). Filter wphub_webp_avif_speed.
• The convert, check and re-convert runs on the screen now work in three parallel lanes (filter wphub_webp_parallel, 1–8), each taking its own share of the images.
• "Check all in the background" and "Re-convert all in the background": the run carries on with the screen or browser closed, as a chain of short requests the site makes to itself, with a watchdog (WP-Cron every minute, and the screen while it is open) that restarts a lane that goes quiet. Refused up front, with the reason, if the site cannot reach itself.
• No more PHP 8.5 deprecation notices from imagedestroy().

0.4.1

• Alt text: a proper pager above and below the list — "Showing 1–20 of 899", Previous/Next, page numbers and a box to jump to a page.
• Alt text: "Next" no longer skips images after you save some on the current page (it now carries on from the last image shown).
• Alt text: the count in the heading goes down as you save, and the cursor moves to the next image's box.
• Alt text: the list uses a wider card.

0.4.0

• Media → Image optimisation (was "WebP images"), in three tabs: WebP & AVIF, Image sizes, Alt text.
• The Quality setting now works. WordPress's image editor ignored it when changing format, so every copy came out at about 86; copies are now made with Imagick or GD directly. "Re-convert all images" redoes existing copies with the current settings.
• Optional AVIF copies for <img> tags, with a check that the web server sends them as image/avif.
• PNG graphics kept lossless when that is no bigger; photographs stay lossy.
• "Load first": the page's first large image is fetched before anything else.
• Image sizes tab: make missing or out-of-date sizes from the originals.
• Media library column, per-image convert/re-convert, and recorded reasons for images that cannot be converted, with "Try again".
• Alt text tab.
• Root-relative image URLs (/wp-content/uploads/…) are served as WebP too.

0.3.0

• Media → WebP images redesigned: status tiles (images with WebP, still to convert, space saved, could not convert) and a new progress bar with percentage, count and time left.
• The bar glides smoothly between the figures each batch reports, instead of jumping; converting, checking and removing each show their own progress.
• Batches run for about 5 seconds instead of 20, so the figures update more often (filter wphub_webp_batch_seconds).

0.2.0

• "Check all images again" on Media → WebP images: looks at every image and converts any size with a missing or out-of-date copy. Changes nothing that is already right.
• Background conversion now waits a minute after an upload, so it no longer runs while WordPress is still writing the image's sizes (which left some sizes without a copy), and queues again if a conversion is already running.
• Files whose WebP came out larger are remembered, so a re-check does not try them again unless the file changes.
• The screen says why "Convert remaining images" is greyed out and how many images are waiting for the background job.

0.1.0

• First release.

13. Support

Email support@wpexpertshub.com. Please include:

• your order ID,
• the plugin version (0.5.3 or whichever you run), your WordPress version and your PHP version,
• whether your server uses Imagick or GD, if you know it (the host can tell you),
• what you did, what you expected and what happened, with any message shown on the Image optimisation screen or in the WebP column, and
• what you already tried.