TinyPNG
The TinyPNG plugin sends your images to the TinyPNG API and saves the compressed result on your server. This page explains which upload option gets compressed files into your bucket, how bulk compression works, and how to fix common problems.
How TinyPNG and WP Media Cloud work together#

The TinyPNG plugin has three options for new uploads. The one you choose decides what ends up in your bucket.
| TinyPNG option | What reaches your bucket |
|---|---|
| Compress new images during upload | Compressed files. TinyPNG compresses while WordPress creates the image sizes, before WP Media Cloud uploads them. |
| Compress new images in the background (recommended) | Uncompressed files. WP Media Cloud uploads them first and is not told when TinyPNG finishes. |
| Do not compress new images automatically | Uncompressed files, unless you compress them before they are offloaded. |
WP Media Cloud has no code that reacts to TinyPNG. It detects the plugin and shows it on the Integrations page, under Image Optimization.
Under the hood#
- TinyPNG compresses on the
wp_generate_attachment_metadatafilter. WP Media Cloud offloads later, on thewp_update_attachment_metadatafilter at priority 110. - WP Media Cloud uploads the main file, each generated size and WordPress’s original image. It does not upload TinyPNG’s WebP or AVIF copies.
- A file that is already offloaded is not uploaded again when TinyPNG compresses it later.
Recommended settings#
In TinyPNG:
| Setting | Recommendation |
|---|---|
| API key | Add it in TinyPNG’s settings, or define TINY_API_KEY in wp-config.php. |
| New uploads | Compress new images during upload. TinyPNG notes this takes a little longer but is more compatible with other plugins. |
| Image sizes | Compress only the sizes your theme uses. Each size uses one credit. |
| Conversion to WebP or AVIF | Leave off. See the next section. Each converted size uses an extra credit. |
TinyPNG’s plugin listing says you get 500 credits per month at no cost.
In WP Media Cloud (Media Cloud > Settings > Offload Behaviour):
| Setting | Recommendation |
|---|---|
| Remove local files | Safe for new uploads when TinyPNG compresses during upload. Keep it off if you plan to use TinyPNG’s bulk compression on offloaded files. |
WebP and AVIF#
TinyPNG’s conversion options (Convert to smallest file type, Convert to WebP, Convert to AVIF) save extra files next to your images on the server. WP Media Cloud does not upload these files to your bucket.
TinyPNG serves them with <picture> elements or server rewrite rules, which look for the file on your server. Requests for images on your CDN never reach your server, so visitors get the original JPEG or PNG. To serve modern formats from the CDN, use a CDN that converts images, such as EWWW Easy IO.
Existing images and bulk compression#
TinyPNG’s bulk compression only works on files that are on your server, and skips missing ones. WP Media Cloud does not upload files again after a bulk run.
- Before offloading: run TinyPNG’s bulk compression first, then offload with the Bulk Migration Tool.
- Already offloaded: follow the steps 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.
- 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 |
|---|---|---|
| New uploads are uncompressed in the bucket | TinyPNG is set to compress in the background, or not at all. | Choose Compress new images during upload. For files already offloaded, follow Upload optimized files again on this page. |
| New uploads are not compressed at all | TinyPNG has no valid API key, or your credits ran out. | Check the API key and your credit balance in TinyPNG’s settings. |
| Bulk compression skips files | The files are no longer on your server. | Switch off Remove local files and use Restore to Server first. |
| Bulk compression worked but the CDN still serves large files | WP Media Cloud does not upload files again after TinyPNG compresses them. | Follow Upload optimized files again on this page. |
| WebP or AVIF images are not served | WP Media Cloud does not upload TinyPNG’s converted files. | Expected. Turn conversion off to save credits, or use a converting CDN. |