Docs

ShortPixel

5 min readUpdated November 9, 2026

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 card on the Integrations tab

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.

  1. WordPress saves the upload and WP Media Cloud sends the original, uncompressed files to your bucket straight away.
  2. ShortPixel’s queue compresses the files on your server.
  3. 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_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 ShortPixel’s shortpixel_image_optimised and shortpixel/a-queue-item-completed actions 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.

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

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

In ShortPixel:

SettingRecommendation
Optimize media on uploadOn. 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 ImagesOff, 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.

  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 uploadShortPixel’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 timeThe 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 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.
ShortPixel cannot optimize offloaded imagesThe 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 404Next-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 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