Docs

EWWW Image Optimizer

5 min readUpdated November 9, 2026

This page covers EWWW Image Optimizer’s compression with WP Media Cloud. It explains when files reach your bucket, which EWWW settings to use, and how to fix common problems. EWWW’s Easy IO CDN is a separate product with its own page: EWWW Easy IO.

Compression or Easy IO?#

EWWW image compressionEWWW Easy IO
What it doesCompresses the image files on your server, locally or with an EWWW API key.A CDN that optimizes and converts images on the fly.
Where it is set up in WP Media CloudNothing to set up. WP Media Cloud detects EWWW.Chosen as the CDN in Settings, as EWWW Easy IO.
This pageYesNo, see EWWW Easy IO

You can use compression on its own, Easy IO on its own, or both.

How EWWW and WP Media Cloud work together#

EWWW card on the Integrations tab

EWWW optimizes new uploads in one of two ways. Which one runs decides when the compressed file reaches your bucket.

Background optimization (EWWW’s normal behaviour). EWWW turns this on by itself after its server test passes. The upload finishes first and EWWW compresses the image a moment later.

  1. WordPress saves the upload and WP Media Cloud sends the original, uncompressed files to your bucket straight away.
  2. EWWW compresses the files on your server in the background.
  3. When EWWW reports that it finished, WP Media Cloud uploads every size again. The compressed files replace the originals in the bucket.

Optimization during upload. If you add define( 'EWWW_DISABLE_ASYNC', true ); to wp-config.php, EWWW compresses during the upload request. WP Media Cloud then uploads the compressed files the first time. Uploads take longer.

In background mode the uncompressed file is live on your CDN for a short time. This is listed under Known Behaviors on the About page in WP Media Cloud.

Under the hood#

  • New uploads are offloaded on the wp_update_attachment_metadata filter at priority 110. Uploads from the block editor are offloaded as soon as the attachment is created, so the editor gets a CDN URL.
  • WP Media Cloud listens to EWWW’s ewww_image_optimizer_after_optimize_attachment action. When it fires, WP Media Cloud replaces its record and uploads all sizes again from your server.
  • That second upload needs the files on your server and Offload on upload switched on.
  • A WP-Cron job 5 minutes after each upload offloads anything that was missed. It skips files that are already offloaded.

In WP Media Cloud (Media Cloud > Settings > Offload Behaviour):

SettingRecommendation
Offload on uploadOn. It also controls the second upload after EWWW finishes.
Remove local filesOff while EWWW runs in the background or you use the Bulk Optimizer. EWWW can only compress files that are on your server.

In EWWW Image Optimizer:

SettingRecommendation
Compression modeFree server compression or an API key both work.
Background optimizationKeep EWWW’s default for faster uploads. Add EWWW_DISABLE_ASYNC only if you want the bucket to receive compressed files the first time.
WebP ConversionOff, unless you use Easy IO. See the next section.
JPG Quality LevelEWWW’s docs advise staying between 50 and 92.

WebP and AVIF#

EWWW’s WebP Conversion saves .webp copies next to your images on the server. WP Media Cloud uploads the main file, each generated size and WordPress’s original image. It does not upload these extra copies.

EWWW’s own docs say its WebP options are not available for offloaded media such as Amazon S3. To serve WebP or AVIF from the CDN, use EWWW Easy IO as your CDN. EWWW says no other WebP setup is needed when Easy IO is on.

Existing images and the Bulk Optimizer#

Run EWWW’s Bulk Optimizer while the files are still on your server. When EWWW reports an attachment as finished, WP Media Cloud uploads it again.

The best order for a new site is: compress the library with the Bulk Optimizer, then offload it with the Bulk Migration Tool. If you already removed local files, bring them back first (see below).

Upload optimized files again#

WP Media Cloud only uploads a file a second time when an optimizer it listens to reports that it finished. Otherwise the copy in your bucket stays as it was first uploaded.

These steps send the optimized versions of files that are already offloaded. They use WP-CLI.

  1. In Media Cloud > Settings > Offload Behaviour, switch off Remove local files.
  2. Bring the files back to the server with Restore to Server on the Dashboard, or run wp wpmc restore.
  3. Run the optimizer’s bulk optimization and wait until it finishes.
  4. Run wp wpmc clear-records. It forgets which files were offloaded on this site. It does not delete anything from your bucket.
  5. If you want the server copies removed again, switch Remove local files back on now.
  6. Run wp wpmc offload. Every attachment is uploaded again and replaces the old copy at the same path.
  7. Purge the cache in your CDN, so visitors stop getting the old copies.

Between steps 4 and 6, some images are served from your server instead of the CDN. On multisite, run the commands once per subsite by adding --url=<subsite URL>.

Troubleshooting#

What you seeWhat it meansHow to fix it
The Media Library shows the uncompressed file size right after uploadEWWW is still compressing in the background.Reload the Media Library after a minute.
The CDN still serves the uncompressed imageThe CDN cached the file before the compressed version arrived. WP Media Cloud does not purge your CDN.Purge that file, or the whole cache, in your CDN.
Images never get compressedEWWW’s background job did not run, or the files were removed from the server first.Switch off Remove local files. Check the Health page for loopback and WP-Cron problems, since background jobs need them.
The bucket keeps the uncompressed versionOffload on upload is off, or the files were not on the server when EWWW finished.Switch on Offload on upload, then follow Upload optimized files again on this page.
WebP images are not servedWP Media Cloud does not upload EWWW’s .webp copies.Use EWWW Easy IO for WebP and AVIF.
The bucket keeps the uncompressed version, and the image has an offload errorThe second upload failed, often because the files were not on the server. WP Media Cloud 1.1.9 or newer keeps the previous cloud record, so the image keeps loading from the cloud.Follow Upload optimized files again on this page.

This website uses cookies to enhance your browsing experience and ensure the site functions properly. By continuing to use this site, you acknowledge and accept our use of cookies.

Accept All Accept Required Only