How to use S3 Image Optimizer

First, it is worth noting that S3 IO is "site agnostic". In other words, if you have images for in your S3 bucket, you do NOT have to run S3 IO on the WordPress install for You could install it at, or, or any site you control. In fact, you can even create a dedicated WordPress install just for running S3 Image Optimizer, with no other plugins needed except EWWW IO and S3 IO.


Now that we have that cleared up, let's get down to business. As mentioned, you need 2 plugins to make this work:  S3 Image Optimizer, and the EWWW Image Optimizer. Then...

  • Make sure you have configured EWWW IO with the settings you want to use.
  • Optionally, enter your license key on the S3 IO settings page to activate plugin updates.
  • Setup your AWS access keys, and then enter your access keys on the S3 IO settings page and save to confirm them.
  • Then, enter the buckets you wish to optimize in the appropriate text area. Leave it empty to have the plugin optimize all your buckets.
  • You can also define constants to restrict S3 IO to a specific bucket and/or sub-folder: S3_IMAGE_OPTIMIZER_BUCKET and S3_IMAGE_OPTIMIZER_FOLDER. These override the bucket list on the settings page, and will look like this (note the lack of leading/trailing slashes on the folder setting):
define( 'S3_IMAGE_OPTIMIZER_BUCKET', 'my-amazing-bucket-name' );
define( 'S3_IMAGE_OPTIMIZER_FOLDER', 'wp-content/uploads' );
  • If your IAM user does not have access to list all buckets, you will generally also need to configure the region, something like this (list of region names):
define( 'S3_IMAGE_OPTIMIZER_REGION', 'eu-west-1' );
  • If you are using an S3-compatible provider other than Amazon, you can define the region and endpoint constants:
define('S3_IMAGE_OPTIMIZER_REGION', 'us-west-004');


  • Go to Media->S3 Bulk Optimizer to start optimizing your bucket(s).
  • Use Media->S3 URL Optimizer to optimize specific images by their url/address.
  • Use WP-CLI to optimize your buckets from the command line, especially useful for large buckets or scheduling bulk optimization:  wp-cli help s3io optimize


Q. What happens if you have too many images and the S3 Bulk Optimizer keeps timing out?

A. First, upgrade to version 2.1, timeouts should now be a thing of the past. Otherwise... If you have configured S3 IO to optimize all your buckets, try a single bucket to see if that will work. If that still doesn't work, use the S3_IMAGE_OPTIMIZER_FOLDER setting above to restrict optimization to a specific folder. This way you can optimize a single bucket by configuring each folder within the bucket, running the S3 Bulk Optimizer, and then moving to the next folder.

A. If the last option has you groaning, see if your webhost supports WP-CLI. Using WP-CLI generally allows you to avoid any timeouts, and solves a whole host of issues with long-running processes. The command above in the Usage section should get you going.

A. If you've tried everything, and WP-CLI isn't an option with your webhost, find a webhost that DOES support WP-CLI. While many webhosts don't support WP-CLI, it's pretty easy to find a cheap host that does, like GoDaddy. Note that I never recommend GoDaddy for hosting, but if you want a cheap solution to run WP-CLI, it works. Remember that S3 IO is site agnostic, so you can run it from a site completely separate from the site(s) that your S3 images belong to. You could also fire up a Digital Ocean droplet with WordPress pre-installed for $5 and put WP-CLI on there. When you're done, you can make a backup image of the droplet and destroy it so that you aren't paying for usage all the time.

Q. What about X, or Y, or maybe even Z?

A. Most problems we've seen are either permissions-related, or covered by the timeout stuff above. If you have a question, shoot us an email via the form below!

Still need help? Contact Us Contact Us