ShortPixel
ShortPixel Image Optimizer compresses images through a queue after they are uploaded. This page explains when compressed files reach your bucket, which ShortPixel settings to use with WP Media Cloud, and how to fix common problems.
How ShortPixel and WP Media Cloud work together#

ShortPixel does not compress during the upload. It adds new images to a queue. The queue runs while a ShortPixel page is open in your browser, or through WP-Cron when Background mode is on.
- WordPress saves the upload and WP Media Cloud sends the original, uncompressed files to your bucket straight away.
- ShortPixel’s queue compresses the files on your server.
- When ShortPixel reports the image as done, WP Media Cloud replaces its record and uploads every size again. The compressed files replace the originals in the bucket.
Until step 3, the uncompressed file is live on your CDN. This is listed under Known Behaviors on the About page in WP Media Cloud.
WP Media Cloud shows ShortPixel 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. - WP Media Cloud listens to ShortPixel’s
shortpixel_image_optimisedandshortpixel/a-queue-item-completedactions to start the second upload. WP Media Cloud 1.1.9 or newer reads ShortPixel’s queue items correctly, so the second upload starts when ShortPixel finishes. - 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 ShortPixel’s WebP or AVIF copies or its backups.
Recommended settings#
In WP Media Cloud (Media Cloud > Settings > Offload Behaviour):
| Setting | Recommendation |
|---|---|
| Offload on upload | On. It also controls the second upload after ShortPixel finishes. |
| Remove local files | Off. ShortPixel compresses the files on your server, and the second upload reads them from there. |
In ShortPixel:
| Setting | Recommendation |
|---|---|
| Optimize media on upload | On. This is ShortPixel’s default. |
| Background mode (Settings > ShortPixel > Processing) | On, so the queue runs through WP-Cron without a browser window open. The compressed files then reach your bucket sooner. |
| Create WebP/AVIF Images | Off, unless you deliver them through the ShortPixel CDN. See the next section. |
WebP and AVIF#
Create WebP/AVIF Images saves extra .webp and .avif files next to your images on the server. WP Media Cloud does not upload these files to your bucket.
ShortPixel’s delivery options that serve these files from your own server do not suit offloaded images. Requests for CDN images never reach your server, and the extra files are not in your bucket. If next-gen markup ends up pointing at your CDN, those .webp or .avif URLs do not exist there.
For WebP or AVIF, use ShortPixel’s Deliver the next-gen images using the ShortPixel CDN option. Or use a CDN that converts images, such as EWWW Easy IO. Test a few pages afterwards.
Existing images#
Compress your library with ShortPixel’s bulk optimization while the files are still on your server. Then offload it with the Bulk Migration Tool. If the library is already offloaded with local files kept, bulk optimization triggers the second upload for each finished image.
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 | ShortPixel’s queue has not processed the image yet. | Turn on Background mode, or keep a ShortPixel page open. Reload the Media Library later. |
| Images stay uncompressed for a long time | The queue only runs with a ShortPixel page open, or WP-Cron is not running. | Turn on Background mode. Check the Health page in WP Media Cloud for WP-Cron and loopback problems. |
| 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. |
| ShortPixel cannot optimize offloaded images | The files are no longer on your server. | Switch off Remove local files and use Restore to Server before optimizing. |
| Broken images, or WebP and AVIF URLs that return 404 | Next-gen markup points at files that are not in your bucket. | Switch off ShortPixel’s local next-gen delivery. Use the ShortPixel CDN option or a converting CDN instead. |
| 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. |