How to Bulk-Convert Your WordPress Media Library to WebP & AVIF

How to Bulk-Convert Your WordPress Media Library to WebP & AVIF

Most WordPress sites accumulate hundreds — sometimes thousands — of JPEG and PNG images over time. Every one of those files is heavier than it needs to be. Modern formats like WebP and AVIF can cut that weight by 30–50%, but manually re-exporting an entire media library isn't realistic.

This guide walks through a complete, no-code workflow for bulk-converting your existing media library using KuDesign ImageIO — a free WordPress plugin that handles scanning, conversion, and server configuration in a single dashboard.

Before You Start: Two Things to Check

1. Server image library support

WebP and AVIF conversion happens on your server using the image editing libraries WordPress has access to — typically GD or Imagick. Most shared and managed hosts support both, but AVIF requires a newer version of Imagick (7.0.25+) and is not available on every host.

KuDesign ImageIO shows you exactly which formats your server can generate directly in the Server Config tab, so you'll know before starting the conversion whether AVIF is available.

If your host only supports WebP, that's still a significant improvement over JPEG/PNG and worth doing.

2. Disk space

Each converted image produces a new file stored under /wp-content/uploads/imageio/. Your originals are never modified. Plan for roughly 40–70% of your current media library size in additional disk usage to accommodate both WebP and AVIF variants.

For a media library of 1 GB, that means setting aside an additional 400–700 MB. On most modern hosting plans this is not a concern, but worth checking on constrained shared hosting.

Step 1: Install KuDesign ImageIO

Install the plugin directly from your WordPress dashboard:

1. Go to Plugins → Add New Plugin
2. Search for KuDesign ImageIO
3. Click Install Now, then Activate

Alternatively, download it from wordpress.org/plugins/kudesign-image-io and upload the zip via Plugins → Add New Plugin → Upload Plugin.

After activation, the plugin appears under Settings → imageIO.

Step 2: Scan Your Media Library

The first step is a scan — this records all eligible JPEG and PNG files (originals plus every WordPress-generated thumbnail size) in the plugin's metadata table. No files are created or modified during this step.

1. Open Settings → imageIO
2. Click One-click scan
3. Watch the progress counter update in real time

The scan runs in resumable batches, so it won't time out even on large libraries. If you close the browser tab during scanning, WP-Cron picks it up in the background and continues until complete.

When the scan finishes, the dashboard shows:

• Total images found
• Total file count (originals + all registered thumbnail sizes)
• Estimated storage impact

At this point, nothing has been converted yet — you're just looking at the inventory.

Step 3: Check Server Capabilities

Before converting, open the Server Config tab. This shows:

• Whether your server can generate WebP ✓ / ✗
• Whether your server can generate AVIF ✓ / ✗
• A live preview test showing whether your current server configuration is returning PNG, WebP, or AVIF for a test request

If AVIF shows as unsupported, you can still proceed with WebP-only conversion — the plugin handles each format independently. Contact your host if you need AVIF support and it's currently unavailable; many hosts can enable it on request.

Step 4: Run the Bulk Conversion

Return to the main dashboard and start converting:

Convert all images at once: Click Start conversion to queue every scanned image for processing. The plugin works through the queue batch by batch. You can watch progress live on the dashboard or close the tab — WP-Cron will continue processing in the background.

Convert selected images only: If you only want to convert specific files (for example, images from a particular upload period, or just originals without thumbnails), use the image list to select them individually and click Convert selected.

During conversion, the dashboard tracks:

For a typical photography-heavy site, you'll see 30–50% savings on JPEG sources. PNG files with large flat color areas (screenshots, diagrams) often compress even more aggressively.

Step 5: Configure Your Server to Serve the New Formats

This is the step most guides skip — and it's the one that actually makes your visitors receive the smaller files.

KuDesign ImageIO keeps your original JPG and PNG URLs intact. A photo that was at /wp-content/uploads/2024/06/hero.jpg stays at that URL. The plugin stores converted versions under a separate path (/wp-content/uploads/imageio/webp/ and /wp-content/uploads/imageio/avif/).

To serve WebP or AVIF to capable browsers from the original URL, your web server needs a rule that intercepts image requests, checks the browser's Accept header, and redirects to the appropriate format if available.

The Server Config tab provides ready-to-use rules for both Apache and Nginx.

Apache (.htaccess)

Copy the provided rules into your .htaccess file, typically in the root of your WordPress installation. The rules look like this in structure:

<IfModule mod_rewrite.c>
  RewriteEngine On

# Serve AVIF if supported and file exists
  RewriteCond %{HTTP_ACCEPT} image/avif
  RewriteCond %{REQUEST_FILENAME} \.(jpe?g|png)$
  RewriteCond %{DOCUMENT_ROOT}/wp-content/uploads/imageio/avif%{REQUEST_URI} -f
  RewriteRule ^ /wp-content/uploads/imageio/avif%{REQUEST_URI} [L,T=image/avif]

# Serve WebP if supported and file exists
  RewriteCond %{HTTP_ACCEPT} image/webp
  RewriteCond %{REQUEST_FILENAME} \.(jpe?g|png)$
  RewriteCond %{DOCUMENT_ROOT}/wp-content/uploads/imageio/webp%{REQUEST_URI} -f
  RewriteRule ^ /wp-content/uploads/imageio/webp%{REQUEST_URI} [L,T=image/webp]
</IfModule>

These rules check the Accept header first. AVIF is offered first (it's smaller), then WebP, then the original falls through as-is. No browser sees a broken image.

Nginx

If your server uses Nginx, the Server Config tab provides equivalent map and try_files directives to paste into your site configuration block.

After adding the rules:

1. Reload your server configuration (sudo systemctl reload apache2 or sudo nginx -s reload)
2. Return to the Server Config tab in ImageIO
3. Use the Preview test to confirm your server is now returning WebP or AVIF

The preview sends a test request with the appropriate Accept header and shows you which format the server actually returned.

Step 6: Verify the Results

With conversion done and server rules in place, verify everything is working:

In the ImageIO dashboard:

• All items show status Done
• Savings column shows meaningful reductions (typically 30–50%)

In Chrome DevTools:

1. Open a page on your site
2. Open DevTools → Network tab → filter by Img
3. Click on any image request
4. Check the Content-Type response header — it should say image/webp or image/avif

In PageSpeed Insights: Run your site through PageSpeed Insights. The "Serve images in next-gen formats" warning — one of the most common suggestions on unoptimized WordPress sites — should either disappear or show significantly fewer flagged images.

Managing Your Converted Images

Deleting generated files

If you need to reclaim disk space or want to revert to serving originals, use Settings → imageIO → Cleanup. This deletes all generated WebP and AVIF files without touching your original media library. Remember to also remove or disable the .htaccess / Nginx rules if you no longer want format negotiation active.

New uploads going forward

Once ImageIO is active, new image uploads are converted automatically. You don't need to run a manual conversion for images added after the initial bulk pass. The plugin queues new uploads and processes them via WP-Cron.

Reconverting after changes

If you update your image quality settings or your host later adds AVIF support, you can run a fresh conversion pass. The plugin will process any images that haven't been converted in the selected format.

What the Pro Version Adds

The free version covers the full bulk conversion and server-serving workflow described above. The KuDesign ImageIO Pro version (currently in development) extends this with:

• OSS / S3 object storage integration — sync converted files directly to cloud storage and serve them from there
• Incremental cloud sync — new uploads are converted and pushed to OSS automatically
• API access — trigger conversions programmatically via REST API for CI/CD pipelines
• OSS-native lazy load — lazy load images served from object storage without JavaScript workarounds

For most WordPress sites, the free version is all you need. The Pro tier is designed for high-volume publishing sites, multi-site installations, or teams that need automated image pipelines.

Common Issues

"Conversion failed" for some images

This usually means the source file is corrupted, uses an unusual color profile, or the server hit a memory limit during processing. Check your PHP memory limit (memory_limit in php.ini) — image conversion is memory-intensive, and 256 MB is a reasonable minimum. The plugin will continue processing other images even if individual items fail.

Server preview shows PNG despite rules being in place

Check that mod_rewrite is enabled (Apache) and that .htaccess overrides are permitted (AllowOverride All in your Apache config). On Nginx, verify you reloaded the configuration after editing. The Server Config tab preview is the fastest way to confirm whether the rules are being applied correctly.

AVIF not supported on my server

Ask your host to upgrade Imagick or enable the libavif library. Alternatively, convert to WebP only — it still delivers a significant improvement and has near-universal browser support. You can add AVIF later once your host supports it.

Summary

The full workflow takes under ten minutes for most sites:

1. Install KuDesign ImageIO from the WordPress plugin directory
2. Run One-click scan to inventory your media library
3. Check Server Config to confirm format support
4. Click Start conversion and let the queue run
5. Add the provided Apache or Nginx rules to serve WebP/AVIF from original URLs
6. Verify with the Server Config preview and Chrome DevTools

Your original files are never modified. You can revert at any time by cleaning up the generated files and removing the server rules. And once the initial bulk pass is done, new uploads are handled automatically.

KuDesign ImageIO is a free plugin by KuDesign Limited, available on the [WordPress plugin directory](https://wordpress.org/plugins/kudesign-image-io/). KuDesign also develops QueryIO, PageIO, and AdminIO.