Smush
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#

- WordPress saves the upload and WP Media Cloud sends the files to your bucket.
- Smush compresses the files on your server.
- When Smush fires its
wp_smush_image_optimisedaction, 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_metadatafilter 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.
Recommended settings#
In WP Media Cloud (Media Cloud > Settings > Offload Behaviour):
| Setting | Recommendation |
|---|---|
| Offload on upload | On. It also controls the second upload after Smush finishes. |
| Remove local files | Off. Smush compresses the files on your server, and the second upload reads them from there. |
In Smush:
| Setting | Recommendation |
|---|---|
| Automatic Compression | On, 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.
- In Media Cloud > Settings > Offload Behaviour, switch off Remove local files.
- Bring the files back to the server with Restore to Server on the Dashboard, or run
wp wpmc restore. - Run the optimizer’s bulk optimization and wait until it finishes.
- Run
wp wpmc clear-records. It forgets which files were offloaded on this site. It does not delete anything from your bucket. - If you want the server copies removed again, switch Remove local files back on now.
- Run
wp wpmc offload. Every attachment is uploaded again and replaces the old copy at the same path. - 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 see | What it means | How to fix it |
|---|---|---|
| The Media Library shows the original file size after upload | Smush has not finished yet. | Reload the Media Library after a minute. |
| The CDN copy is still the uncompressed original | The 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 images | The 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 served | WP 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 break | The 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 error | The 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. |