Docs

Smush

4 min readUpdated November 9, 2026

Smush compresses images on upload and in bulk, and Smush Pro adds WebP and AVIF formats and a CDN. This page explains when compressed files reach your bucket, which Smush settings to use with WP Media Cloud, and how to fix common problems.

How Smush and WP Media Cloud work together#

Smush card on the Integrations tab
  1. WordPress saves the upload and WP Media Cloud sends the files to your bucket.
  2. Smush compresses the files on your server.
  3. When Smush fires its wp_smush_image_optimised action, WP Media Cloud replaces its record and uploads every size again. The compressed files replace the originals in the bucket.

If Smush finishes after the first upload, 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.

WP Media Cloud shows Smush on the Integrations page, under Image Optimization.

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.
  • The second upload reads the files from your server. It only runs when Offload on upload is on.
  • WP Media Cloud uploads the main file, each generated size and WordPress’s original image. It does not upload Smush’s WebP or AVIF copies.

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

SettingRecommendation
Offload on uploadOn. It also controls the second upload after Smush finishes.
Remove local filesOff. Smush compresses the files on your server, and the second upload reads them from there.

In Smush:

SettingRecommendation
Automatic CompressionOn, for the image sizes your theme uses. Each selected size is compressed as WordPress creates it.
Next-Gen Formats (Pro)Off. See the next section.
Smush CDN (Pro)Off. Smush’s docs say its CDN cannot serve images offloaded to third-party cloud storage. Use the CDN set up in WP Media Cloud.
Amazon S3 integration (Pro)Off. Smush documents it for the WP Offload Media plugin, not WP Media Cloud.

WebP and AVIF#

Smush’s Next-Gen Formats feature saves WebP or AVIF versions on your server. WP Media Cloud does not upload them to your bucket.

Smush’s docs also say images offloaded to cloud storage are not served in next-gen formats by this feature. The Server Configuration method needs requests to reach your web server, and CDN requests do not. To serve modern formats from the CDN, use a CDN that converts images, such as EWWW Easy IO.

Existing images#

Run Smush’s bulk optimization while the files are still on your server. When Smush reports an image as done, WP Media Cloud uploads it again. For a new site, the simplest order is: bulk compress first, then offload with the Bulk Migration Tool.

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 original file size after uploadSmush has not finished yet.Reload the Media Library after a minute.
The CDN copy is still the uncompressed originalThe second upload did not happen, or the CDN cached the old file.Purge the file in your CDN first. If the bucket copy is still large, follow Upload optimized files again on this page.
Smush cannot compress offloaded imagesThe files are no longer on your server.Switch off Remove local files and use Restore to Server before a bulk run.
WebP or AVIF images are not servedWP Media Cloud does not upload Smush’s next-gen files, and Smush does not serve them for offloaded images.Expected. Use a CDN that converts formats, such as EWWW Easy IO.
Images load from a Smush CDN address, or breakThe Smush CDN is on alongside WP Media Cloud.Switch off the Smush CDN.
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