This guide explains how to use Smush Pro’s Image Optimizing features to compress, resize, and share all your images without sacrificing quality. Use the Index on the left to quickly locate usage guidance on specific Smush features.

Smush aims for the best possible compression/quality ratio for every image, regardless of its filesize. For example, Smush will run a lossy compression when converting jpg to webp, but will do lossless for png to webp.

If you haven’t installed Smush yet, then you should visit the Smush Pro page where you can explore the plugin’s many features, and where WPMU DEV members can install Smush Pro directly to any connected site.


Every WPMU DEV hosted site comes fully loaded with Pro versions of the following plugins automatically installed for you: Smush, Hummingbird, Defender, SmartCrawl and Forminator. Not hosting with us yet? Check out our Hosting page to see if we might be a good fit for your projects.

Privacy Policy Information

Upon activation or when certain features are configured, this plugin may add cookies to the user’s browser, store personal information in your database, or integrate with 3rd-party applications. You may need to disclose this information to your site visitors. For details, see Our Plugins in our privacy policy documentation.

Pro Tip

Advanced users can leverage some simple WP-CLI commands to optimize, list, and restore images with Smush Pro. See this API doc for more info.

Optimize Your Builder

We’ve put together some awesome tutorials on optimizing content & pages created with some of the most popular page builders out there. If you’re using any of the ones listed below, we highly recommend checking out the associated posts to help you get the most out of Smush.

Optimize Elementor Using Smush and Hummingbird
Optimize Elementor for Core Web Vitals Using R.O.S.E.
Optimize WPBakery Sites
Optimizing WPBakery’s Impreza Theme
Optimize Divi with Hummingbird and Smush
Optimizing Astra with Hummingbird and Smush
How to Speed Up Slider Revolution in WordPress
Speed Up and Optimize Avada Using Smush and Hummingbird

The Dashboard reports your Smush stats and provides an overview of enabled features.

The Dashboard reports your Smush stats and provides an overview of enabled features.

The Bulk Smush feature allows you to apply all your enabled features to any uncompressed images with a single click. The Pro version allows you to Bulk Smush an unlimited number of images at a time, up to 32Mb per image. The free version allows up to 50 images with one click, with a maximum of 5Mb/image.

Note that, on WordPress Multisite networks, Bulk Smush is not available by default and needs to be enabled in the Network Admin Smush settings. Once it has been enabled, Bulk Smush will be available on the subsites.

Recommended Reading

Our blog post, How To Bulk Optimize Images With Smush, explains how to get the most out of the bulk optimization feature.

The Bulk Smush module will alert you to uncompressed images in your Media Library. Click Bulk Smush Now to compress all un-Smushed images. Alternatively, click Media Library to open the library and compress images individually as described in Media Library below.

Click Bulk Smush Now to compress all un-Smushed images.

Additionally, you can trigger an immediate scan of your image library at any time by clicking Re-Check Images.

you can trigger an immediate scan of your image library at any time by clicking Re-Check Images.


With Automatic Compression and all other features enabled, you may seldom need to Bulk Smush as your images will be compressed during the upload process.

8.2.1 Bulk Smush Settings

Link to chapter 2

The Settings features are your primary optimization tools.

Recommended Reading

Our blog post, How To Ace Google’s Image Page Speed Recommendations With Smush, focuses on Smush features that directly impact your Google Page Speed score.

Image Sizes

The Image Sizes feature allows admins to choose which thumbnails they want to be compressed and which ones Smush should ignore.

In order to serve scaled images, WordPress generates multiple copies in different sizes of every uploaded image. Some themes and plugins also require copies. These copies, called thumbnails, can add up quickly, so we recommend you compress all thumbnails.

Pro Tip

WordPress duplicate images are a net positive for most users – a simple exchange of storage space for faster page speed. WordPress pros, on the other hand, achieve page speed in many ways and the benefits of duplicate images may be minimal. Follow the Learn More link for guidance on preventing WordPress from creating multiple copies of your uploaded images.

Click Custom to reveal a list of the thumbnail sizes that WordPress is creating on your site. Select the checkboxes for the images you want to be compressed, and leave those you don’t want compressed unchecked. The image sizes you select will be compressed automatically upon upload if you have Automatic Compression enabled.

Select thumbnail sizes to optimize with Bulk Smush users

If your site is hosted on either a Business or an eCommerce plan at, and you have the Site Accelerator option enabled in the Jetpack plugin, you will not be able to bulk smush your images. That is because that feature in Jetpack offloads image thumbnails to’s own CDN and Smush cannot fetch them to optimize them for you.

Users of the free version of Smush on sites will see a notice like this when that Jetpack feature is enabled:


If you are a Smush Pro user, you will still be able to optimize your original full-size images if you enable the Compress uploaded images option below.


Automatic Compression

Click the slider to enable automatic compression, and Smush will compress every image copy WordPress generates as soon as it’s created. Smush will only automatically compress the image sizes you selected in the Image Sizes setting above.

Enabling this option will ensure that all images are automatically optimized when they’re uploaded regardless of the method used to upload them: through the media library uploader, through WordPress or WooCommerce Rest API, or via WordPress mobile apps.

enable automatic compression


Our well-designed multi-pass lossy compression reduces file sizes significantly by stripping out as much data as possible without reducing image quality. Click the slider to enable multi-pass lossy compression.

enable super-smush images


If yours is a photography site, you may want to retain the metadata that digital equipment frequently attaches to your images, but for most sites, it is entirely unnecessary. Click the slider to enable Smush to strip unnecessary metadata from all images.

Optimized Images Color Inconsistencies

Please note that EXIF metadata might contain data related to the image’s color profile. Removing such data might alter the original colors of the image.

strip metadata from images

Image Resizing

As of version 5.3, WordPress creates a scaled version of uploaded images over 2560x2560px by default, and keeps your original uploaded images as a backup. If desired, you can choose a different resizing threshold or disable the scaled images altogether.

To use images larger or smaller than 2560x2560px, enable Resize uploaded images and define a new resizing threshold. Your original uploaded images will still be kept as a backup.

To disable automatic resizing of images altogether, enable Disable scaled images. Scaled versions of images will not be generated, and only your original uploaded images will be kept.

Note that WordPress excludes PNG images from automatic image resizing. As a result, only uploaded JPEG images are affected by these settings.

Image resizing options in Smush

Uploaded Images

By default, WordPress will only compress attachments generated when images are uploaded, and not the uploaded images themselves. To compress your uploaded images, enable Compress uploaded images.

To save a copy of your uploaded images, enable Backup uploaded images. If enabled, keep in mind that saving a copy of uploaded images can significantly increase the size of your uploads folder.

Original image options in Smush

Better image control

To learn more about the new image resizing & compression options, see How to Compress and Remove Original Images with Smush on the blog.

PNG to JPEG Conversion (Smush Pro only)

Click the slider to enable this feature and Smush will convert PNG files to JPEGs, but only when doing so results in a smaller file size.

auto convert PNGs to JPEGs

8.2.2 Media Library

Link to chapter 2

When activated, Smush adds features to your Media Library that allow you to filter images by Smush status, selectively compress images and view the Smush stats associated with each image.

Use the Smush filter to display all images, just those that were ignored or those not yet processed. Smush does not compress video or Gif files. Any other ignored image types could indicate that you are not making full use of all available compression features.

smush media library filters

Smush adds a column to the Media Library indicating whether an image has been compressed or not. Images that have not been processed by Smush can be compressed by clicking the Smush link for that image.

You can also exclude images from being compressed using Bulk Smush by clicking the Ignore link.

Choose to Smush or Ignore individual images

If you want to allow Bulk Smush to compress images that you have set to ignore, click the Undo link for that image.

Undo - Ignored from auto-smush

Once an image has been processed, you can click the View Stats link to reveal a list of the thumbnail copies WordPress has created for that image, along with the sizes of those files before and after compression.

view stats for an image

8.3 Directory Smush

Copy chapter anchor to clipboard

Your Uploads folder is the primary folder for images, but images can reside elsewhere. Plugins that create their own image copies, for example, may store those images in the plugins folder. Directory Smush finds uncompressed images stored outside the uploads folder and allows users to compress those images if they wish.

Directory smush

Activate the feature, then click Choose Directory to reveal a list of directories where uncompressed images are located. Click the arrow to the left of any directory to reveal a list of subdirectories, and click the arrow to the left of any subdirectory to reveal the images within.

choose folder for directory smush

Click the checkbox next to any directory or subdirectory to compress all the images they contain or select images individually if you wish, then click Choose Directory to begin compression. If several directories are selected, the process could take several minutes.

directory smush in progress

Lazy loading retrieves only the data necessary to display what is actually being viewed at any given moment and can have a dramatic impact on page speed. The heavier your site is with images, the greater the benefit. The feature’s settings allow you very specific control over what file types are lazy-loaded, as well as when and where that occurs.

To enable lazy-loading, select Lazy Load in the Smush menu and click Activate.

To enable lazy-loading, select Lazy Load in the Smush menu and click Activate.


Smush Lazy Load may not work as expected if Lazy Load is enabled in any other active plugins. For best results, activate Lazy Load in only one plugin at a time.

Also note that the Lazy Load feature is not available for background images.

Media Types

You can choose which media types are lazy-loaded and which are not by selecting or deselecting the file type checkboxes.

Media types

Output locations

You can choose where lazy loading is applied by selecting or deselecting the out location checkboxes.

select lazy load output locations

Display & Animation

You can choose how images appear as they scroll into view by selecting an animation effect, a placeholder image or no effect at all.

Fade In

Images will load first and then begin to fade in. Set the duration of the fade-in milliseconds by entering how long the fade should be from start to finish into the Duration field. The fade will begin as soon as any part of the image scrolls onto the screen. You can delay the fade if you want the animation to occur with the entire image in view by entering the delay time in milliseconds into the Delay field.

lazy load fade in animation


Choose the Spinner if you want a spinner to display while images fully load. Use the uploader to upload a custom spinner if you wish.

lazy load spinner animation


If you want a custom placeholder image to display while images load, use the uploader to upload your image. There are two images already present that you can choose to display as well. You can add a background color if you wish by using the color picker provided. Of course, you can simply choose None and containers will remain empty until images are fully loaded.

lazy load display & animation placeholder


Post Types

You can choose which post types use lazy loading and which ones don’t by enabling or disabling the slider for each post type.

Choose the post types you want to lazy load

Post, Pages, URLs, Classes and IDs

Disable lazy loading for individual URLs by entering the URLs into the field provided, one URL per line. You can do the same with classes and IDs by entering them into the field, one class or ID per line.

lazy load include/exclude URLs, classes and IDs


By default, the scripts required to support a page’s functionality are placed in the footer to facilitate faster page speed, but there may be times when you need scripts to load early. Choose whether scripts load in the header or footer by clicking the corresponding button.

NOTE: Your theme must be using the wp_footer() function for this feature to work. The function should be located in your wp_include folder, or you can simply contact your theme’s developer and inquire about whether the function is present.

lazy load scripts in header or footer

Native lazy load

Click the Enable native lazy loading toggle to enable support for native browser lazy loading.

enable native lazy loading

In some cases, this can cause the Google PageSpeed audit to fail the “Defer offscreen images”. Disable native lazy loading to rectify this.

Disable Noscript

If you are using W3C’s validation tool, you may experience errors due to No Script on your pages. Click on the Disable Noscript toggle to avoid this issue.

disable noscript


If you no longer want to use the lazy load feature, you can deactivate it at any point by clicking Deactivate.

One of the major factors that can make your site slow is the distance your content has to travel between the hosting server and the location of the visitor viewing your site. Generally speaking, the further the location, the longer your site will take to load. A chief value of CDNs is that they pre-position your content in servers around the world thereby reducing the distance your content has to travel no matter where a visitor is located. Check out our CDN overview video for more information.


A valid SSL certificate installed on your domain is required for the CDN to function without error. If you are using Cloudflare and getting Error 526: Invalid SSL certificates, you’ll want to review Cloudflare’s help doc here to resolve the issue.

Faster initial load time

As images served from the CDN need to be cached before being served, Smush will temporarily serve the original image until the image is cached. Once the caching process is complete, Smush serves it from the CDN.

Uploads directory outside the WordPress root?

Unconventional WordPress configurations where the uploads directory is located outside of the WordPress root are not supported by the Smush CDN. If you are experiencing issues after enabling the CDN on such an install, please contact our support team who will investigate and provide a customized workaround if possible.

To enable the Smush CDN, select CDN in the Smush menu and click Get Started.

To enable the Smush CDN, select CDN in the Smush menu and click Get Started

The Smush CDN consists of 40 terabytes-per-second servers located in 45 locations around the world. Closer servers mean faster speeds and faster speeds mean better page rank. Our CDN also ensures that a larger number of users can visit your site at the same time, without causing delays in content delivery.

Note: Enabling the CDN will have no impact on the Bulk Smush or Directory Smush features, as those run independently from the CDN.

Supported Media Types

Smush CDN can serve the following media types: JPG, PNG, GIF, and WebP (SVG format is not supported).

CDN supported media types

Note: If you are trying to serve large GIF images on your site, they may timeout. If you experience this issue, try to replace the large GIFs with smaller ones or consider using a different file format.

The CDN does not currently support videos. We recommend you consider a third-party provider specializing in video hosting and that you embed the videos into your posts and pages.


If you are using the WP-Retina 2x plugin and also want your retina images to be served via the Smush CDN, you’ll need to add the following constant to your wp-config.php file, just before the line that says “That’s all, stop editing“:
Unchanged: define ( WP_SMUSH_CDN_DELAY_SRCSET, true );

Background Images

When enabled, background images that have been declared with CSS will be served from the CDN whenever possible.

For this feature to work, your theme’s background images must be declared correctly using the default wp_attachment functions. Non-media library uploads can still be compressed using the Directory Smush feature, they just won’t be served from the CDN.

Click the slider to enable Smush to serve your background images from the CDN. When disabled, background images will be served from either your primary server, which we do not recommend, or from a third party if you’ve invested in one.

serve background images from CDN

Note that the Smush CDN is able to serve background images only if they are served via the <img> HTML tag or via an inline CSS style at a <div> or when declared in a <style> HTML tag. The Smush CDN does not serve background images added to your website in a CSS stylesheet.

The Smush CDN will serve background images using the following methods:

It will not serve background images using the following method:


Right-click on your background image and use the browsers built-in inspector to see what method your theme/plugin is using to serve your background images. If you need help contact our 24/7 live support team.

Automatic Resizing

Improperly-sized images can impact page speeds, and this feature allows the CDN to automatically resize any images that do not fit their containers. This resizing occurs when the images are served and has no impact on the size of the original image.

enable automatic resizing

How Automatic Resizing works

Every image served to the user’s browser gets a sizes attribute with a max-width as defined by the content_width in your active theme. For example, if your theme defines the content_width as 1000px, then that would be the largest image size served to the user’s browser, even if the original image is larger. If the original size of an image is smaller than the content_width, then the largest size of the image served will be its original size.

The image below illustrates what you might see in your browser’s developer tools for the example above. The srcset contains several possible image sizes that can be served depending on the browser’s viewport size. But even though the original image in this example has been scaled to 2048px wide, the max-width that will be served is 1000px because that’s what is defined in the theme for the content_width.

max-width size example in source code

Note that if you hardcode the width of an image directly in its HTML like < img width="800" src="image.jpg" / >, then that width attribute would override the srcset and that would be the image size served to the browser, regardless of what is set for the content_width in the theme. You would see that width attribute appear in the Styles section of your browser’s developer tools as img[Attributes Style]

Example of hardcoded image width in source code

If you resize an image via CSS, that would of course affect the image appearance on screen, but it would not affect the sizes available to the browser in the image srcset.

As an example of the above, let’s say your theme defines content_width as 1000px, and you have an original image that is also 1000px wide, but your stylesheet contains CSS to adjust the width of the image to 90%. The image will appear at 900px on screen, but the image sizes attribute will still have 1000px as the max-width. So that 1000px image would still be the image size served, which would then be resized by your CSS. The reason for that is that by the time the CSS loads, the image has already been loaded in the browser and its srcset defined.

Example of image resized in CSS

Note that if your theme does not define the content_width, or if it is defined incorrectly, then the largest image size in the srcset will be the plugin default of 1920px, unless you have set a smaller size in the Image Resizing option in Smush. If you set a size smaller than your theme’s content_width in Image Resizing, then that would be the largest size served to the browser for your full_size images.

WebP Conversion

Smush can automatically convert and serve your JPG and PNG images as WebP to compatible browsers. Conversion is lossy when converting from jpeg images, and lossless when converting from png images.

We’ll detect and serve WebP images to browsers that will accept them by checking Accept Headers and gracefully fall back to your normal PNGs or JPEGs for non-compatible browsers.

Enable WebP conversion

Rest API

Click the Enable REST API support toggle to allow Smush to automatically replace image URLs when fetched via REST API endpoints.

enable rest api support


You can disable the CDN feature by clicking Deactivate.

deactivate CDN

Staging Environment

Smush CDN cannot fetch images from a password-protected site. Since the Staging environment for WPMU DEV hosted sites is always password-protected, Smush Pro will automatically serve media from the local server when active in a Staging environment.

Smush CDN staging environment warning

If you move your Staging files into Production, your Production environment’s media will automatically be served from the Smush CDN.

Local Development Environment

Smush CDN cannot fetch images from a local development environment such as those built with XAMPP, MAMP, etc. The site must be publicly accessible for this feature to work.

Smush Pro will automatically serve media from the local server when active in a local environment.

Error Handling

The URL of any image served from the Smush CDN will of course be different than the URL for that same image in your media library, as it’s not coming from your site. The URL would look something like this:

Where the 1st XXXXXX is your public WPMU DEV user number, and the 2nd is the public ID of the site connected to your Hub.

If there is any issue fetching an image from the CDN URL, we’ll redirect the image to load from its original media library URL, so your users won’t even know there’s a problem.

We’ll pass the error message information in the page headers during this time in case you need it for troubleshooting.

In most cases, errors are intermittent and resolve themselves within an hour or two. But if you do need help resolving a CDN issue, don’t hesitate to reach out to our support superheroes for assistance.

8.5.1 Bandwidth and Upgrades

Link to chapter 5

CDN bandwidth usage is reported in the Smush overview module. Under normal bandwidth usage, the CDN status will be reported as Active. When you’ve almost reached or exceeded your bandwidth, the CDN status will be reported accordingly.

CDN status bandwidth


Your WPMU DEV membership includes the following CDN bandwidth allotment by default:

  • Free – 0
  • Basic – 5Gb
  • Standard – 10Gb
  • Freelancer – 20Gb
  • Agency – 50Gb

More CDN bandwidth can be purchased as needed, and your Smush CDN bandwidth plan can be upgraded or downgraded at any time. Check out our CDN plans:

  • 50GB – $5/m
  • 100GB – $10/m
  • 250GB – $20/m
  • 500GB – $30/m
  • 1TB – $50/m
  • 5TB – $200/m
  • 10TB – $350/m

For more information about tracking bandwidth usage and guided instructions for increasing and checking your plan, visit our Smush CDN bandwidth documentation.

8.5.2 Filters

Link to chapter 5

This chapter outlines a few handy filters you can use to modify default Smush CDN behavior if needed.

Excluding Images from the CDN

There may be times when you wish to exclude one or more images from the Smush CDN. For example, full-screen images in a slider getting resized by the Automatic Resizing option.

While there is no option in the plugin itself to exclude specific images from the CDN, there is a filter that can be used to achieve this:

The filter can be used in your active theme’s functions.php file, or in a mu-plugin uploaded to your site. For more on using mu-plugins, see our Installing Mu-plugins documentation.

Exclude a Single Image

To exclude only a single specific image from the CDN, use this code and adjust the image URL in the $src variable:

Exclude Multiple Images

To exclude multiple images from the CDN, use the following code instead. Adjust image URLs in the $skip_images array and add/remove as needed (note only the last entry in the array should not have a comma at the end).

Use a Different Attribute for Images in Content

By default, the WPMU DEV CDN will use the data-src or data-srcset attributes of your images to serve them to the browser. However, if you have a plugin or theme that uses a different attribute for in-content images, for example data-desktop, you’ll notice they are not being served from the CDN.

You can use the following filter to instruct the CDN to use that attribute instead. Change data-desktop in the following code to the correct attribute if different.

Use a Different Attribute for Background Images

Similar to the above, you can use the following filter to instruct the CDN to use a different attribute for images that have been added as background images. Here as well, change data-desktop to the correct attribute if different. Please also review the Background Images section above for details about supported methods.

Change Background Image URL

Use this filter to swap the background image URL for a different one. Change the URL in the code below to the actual URL of the image you need to use.

Disable Auto-Resize for Selected Images

This filter only applies if you are using the Automatic Resizing feature in Smush CDN.

If you are experiencing issues with some plugin or theme generated images not displaying properly when using the Automatic Resizing feature, you can use the smush_skip_adding_srcset filter to exclude them. Below are some example uses of this filter:

Skip a specific image

Skip a list of images

Skip all image URLs that contain /preloader.png

The Local WebP feature in Smush Pro enables you to serve images from your Media Library in next-gen WebP format, without relying on the Smush CDN.

The conversion to webp is lossy when converting from jpeg images, and lossless when converting from png images.


Once you have configured this feature, you will need to run the Bulk Smush again for your existing images to get a WebP version created for each one.

This feature only works for images in your Media Library; it cannot create .webp versions of images located in other directories.

When you run Bulk Smush, this module will create a /smush-webp/ folder in the wp-content directory that replicates the structure of your /uploads/ folder, and will create and store .webp versions of all your images there.

The server rules you’ll configure below will take care of searching for those newly created next-gen format images inside that folder and serving them to your site. If there’s no WebP file for a specific image, the original JPEG/PNG gets served.

Recommended Reading

Local WebP conversion is an awesome alternative to using the CDN. For a quick and comprehensive guide to the local WebP feature and how to set it up, check out our blog on Smush Local WebP Conversion.

To enable local WebP, select Local WebP in the Smush menu and click Get Started.

To enable local WebP, select Local WebP in the Smush menu and click Get Started

If your site is hosted externally, follow the Local WebP setup wizard. If your site is hosted by WPMU DEV, local WebP will be automatically preconfigured, and you can skip to the final step.

Step 1 – Choose Server Type

Smush will attempt to detect your server type as either Apache or NGINX. If your server type was not automatically selected, or the detected type is incorrect, select the appropriate server type and click Next. Note that Windows IIS servers are not supported for Local WebP; consider using the CDN WebP option instead.

webP Wizard - Step 1

Step 2 – Add Rules

If your server type is Apache, Smush can automatically apply WebP conversion rules to the .htaccess file located in your site’s root directory. Alternatively, click Manual and follow the on-screen instructions to apply these rules yourself.

webP Wizard – Step 2 (apache)

If your server type is NGINX, WebP conversion rules must be added manually. Follow the on-screen instructions to apply these rules yourself.

If you do not have access to your NGINX config files, you will need to contact your hosting provider in order to facilitate these changes.

webP Wizard – Step 2 (nginx))

In standard nginx.conf configurations, these rules should be added after the root location directive. However, if you are using a complex custom configuration, you may need to place the rules elsewhere in your .conf file.

Proxy / Hybrid Setups

If your server is running NGINX as a proxy for Apache, the Apache/Litespeed rules may not work in .htaccess, and you’ll need to add the NGINX rules manually instead.

If your server uses a hybrid setup running both NGINX and Apache (such as Cloudways or Nexcess), your images are most likely to be cached and served via NGINX. As such, in order to use Smush’s Local WebP feature, you will need to make the following changes:

  1. Exclude image extensions from NGINX rules so those files are now served via Apache.
  2. In Smush, go to the Local WebP page and follow the setup wizard’s guide to add Apache rules.
  3. Clear all cache and refresh your page.

After WebP conversion rules have been configured, click Check Status.

Step 3 – Finish Setup

If you’d like to convert existing images to WebP, click Convert Now to be redirected to the Bulk Smush page to start smushing your images.

Otherwise, click Finish to finish the setup process.

webP Wizard – Step 3


For WordPress multisite installations, WebP versions of existing images in the Media Library can only be created by ‘smushing’ the originals using the Bulk Smush tool on each individual subsite.

Revert WebP Conversion

If you need to delete the WebP files from your server for any reason, such as if your storage space is reaching its limit, you can delete them easily. To completely remove WebP files from your server, click Delete WebP Files.

revert webP conversion

Note that this option will only delete image files created by the Local WebP module, and will not delete any WebP files served by the Smush CDN.


To deactivate the Local WebP module, click Deactivate. Your original JPEG/PNG images will then be served instead of the local WebP images.

deactivate local webP

The deactivation process will also create a disable_smush_webp file inside the /smush-webp/ directory checked by the Smush Local WebP server rules added at the time of configuration. As long as this file exists, your original JPEG/PNG images will be served. If you re-enable Local WebP, the disable_smush_webp file will be deleted and WebP images will be served without issue.

This can also come in handy when troubleshooting when you don’t want to delete your WebP files.

8.6.1 Verifying WebP Output

Link to chapter 6

Unlike the WebP Conversion option in the Smush CDN, you won’t see the .webp format appear in source code, as the images are not served via a CDN with this feature.

Instead, if you want to verify that images are indeed served as webp, you’ll want to pop open your browser’s developer tools and click on the Network tab. Then reload the page to get fresh data in there and check the Response Headers for any image. If you see “content-type: image/webp” there, that tells you that the browser is indeed serving up the webp version of the image.


8.6.2 Local WebP Integrations

Link to chapter 6

Note that if the Amazon S3 Integration is active in Smush Pro > Integrations, images that are offloaded to AWS will not be served in .webp format with this module. Only locally stored images will be served in .webp format. The Status message at the top of the module will display a reminder of this:


8.6.3 WordPress in its Own Directory

Link to chapter 6

When you install WordPress in its own directory, it inherits the DOCUMENT_ROOT of the parent directory. So if, for example, your WordPress is installed in a directory called “mysite” inside “public_html“, the document root of that site would still be public_html, not public_html/mysite

The Local WebP feature in Smush Pro will display the rules it needs with what it sees as the document root (public_html in the above example), and you would need to adjust those rules in a few places to include the directory where your WordPress is installed.

The examples below show where the rules need to be adjusted for each server type. For each instance where you see SUBDIR_HERE before wp-content, change SUBDIR_HERE to the actual directory name where your WordPress is installed.


The rules for Apache/Litespeed servers need to be adjusted in 3 places, as follows:

Note that these rules may not work in the root .htaccess file on some server setups, so you may want to try adding them to the .htaccess file in the wp-content/uploads folder inside your WordPress directory instead.

If the above rules do not work for your specific install, try modifying line #8 to this instead:
RewriteRule wp-content/uploads/(.*.(?:png|jpe?g))$ /SUBDIR_HERE/wp-content/smush-webp/$1.webp [NC,T=image/webp]


The rules for NGINX servers need to be adjusted in 2 places, as follows:

Gutenberg Support

Click the slider to add Smush Stats to Gutenberg blocks. When enabled, a Smush Stats category is added to the page and post editors and appears in the Blocks tab of any post or page containing an image. Click any image on the page to see sizes available for that image, allowing you to choose the smallest file that meets your needs on that page.

gutenberg support with smush

Gravity Forms

If you are using Gravity Forms plugin on your site, enable this integration to ensure that all images uploaded via your forms are also optimized.
Enable Gravity Forms Integration

WPBakery Page Builder

When you add images at custom sizes using the WPBakery Page builder’s editor interface, it does not actually save a thumbnail copy of that image at that custom size. Rather, it creates those image sizes on-the-fly as the image is requested in the browser.

WPBakery custom image sizes

Enable this feature to ensure all such custom-sized images added via the page builder are also optimized when they are served to the user’s browser.

Enable WPBakery Page Builder integration

Amazon S3 (Smush Pro only)

This feature cannot be enabled unless you have an Amazon S3 account and the WP Offload Media plugin installed.

If you are using S3 to store images and WP Offload Media to manage the uploads, then enable this feature and Smush will compress any images contained in your S3 buckets, significantly reducing your cloud storage usage. This feature works together with Bulk Smush Automatic Compression, so be sure to have that feature enabled in the Bulk Smush settings.

amazon s3 integration

Pro Tip

If you wish to offload your existing media library content to your Amazon S3 bucket using the WP-Offload Media plugin, note that you will need their Pro version for that feature; the free version can only offload media uploaded after that plugin is installed on your site. If you need help setting up the integration, there is an excellent walkthrough available on the WP-Offload site here:

If you’re using NextGen Gallery to manage your image galleries, then enable this feature to add Smush Pro commands and stats to the NextGen interface.

Enable Nextgen Gallery integration

smush pro tab in NextGEN

When enabled, a column is added to the Gallery Manager showing the filesize reduction Smush was able to achieve with each image. The NextGen integration also adds a Smush button to the manager so unSmushed gallery images can be compressed and a Restore button so users can return compressed images to their original states.

smush buttons in NextGen manager

The Smush tools are additional features to help improve your site management. The tools currently available are:

Image Resize Detection

The Image Resize Detection tool conveniently highlights any images that are either too large or too small for their containers. This is especially helpful to ensure that you are consistently delivering high-quality images in your galleries, and lowers the risk of you unknowingly serving blurry undersized images. Learn more in the video below.

Click on the Detect and show incorrectly sized images toggle to enable this feature and click Update Settings to save your changes.

enable image resize detection

If this is enabled, when you view your site on the front end, you will notice an Image Issues section in your right sidebar.

image issues sidebar

NOTE: Only site administrators will see this information and the front end will remain unchanged for any visitors.

Both oversized and undersized images will be listed with the actual size of the image in a yellow bubble and the recommended image dimensions in a green bubble. Hover over each numbered block for a note recommending the ideal image size for that container, or click on it to be redirected to the image in question. The image that is associated with the numbered block you just clicked will flash once with a gray cast to indicate that it is the image you have selected.

If all the images on the page are the correct size or there are no images on the page, you will see a note stating that All images are properly sized under the same Image Issues section.

all images properly sized note

Bulk Restore

This feature regenerates thumbnails using your original uploaded images. Keep in mind that if Compress Uploaded Images is enabled in the Bulk Smush settings, your thumbnails can still be regenerated, but the quality will be impacted by the compression of your uploaded images.


The Bulk Restore feature will only work to restore the originals for images that have been uploaded to the /uploads/ directory via the media library. This feature will not restore any images that have been optimized using Directory Smush. If you need to restore optimized images in a directory other than the /uploads/ directory, you will need to restore those manually.

Click Restore Thumbnails to start the restoration process.

Restore thumbnails in Smush

You will then be met with a confirmation request. Click Confirm to follow through with the restoration. Alternatively, click Cancel or the X icon to exit without initiating the restoration.

restore thumbnails confirmation

The restoration process will be tracked by a progress bar and you can cancel the process by clicking on either of the X icons.

restoration progress bar

If the bulk restoration has been successful, you will receive a success message. Click Finish to complete the process.

bulk restoration complete

If Smush has run into any errors while trying to bulk restore your thumbnails, you will receive a message informing you of which images were not regenerated.

unrecoverable images message

Click Retry to run the bulk restoration again or Cancel to close the message. You can view the unrecovered images in your media library by clicking on the arrow icon for each image.


Backup Uploaded Images must be enabled in the Bulk Smush settings in order to bulk restore your images.

The Settings module allows you to change the default Smush settings for translation, plugin data, accessibility, and more.

8.9.1 General

Link to chapter 9


Smush will automatically use the language set in your WordPress Admin Settings as the Active Translation language, provided there is a matching translation available.

Set language to use in Smush

In order for the Active Translation language to reflect in Smush, please ensure that the Smush translation file for the relevant language has been added to your site. Read our WPMU DEV Translations document for a detailed guide to exporting and using translations. Translation files for Smush can be found here.

Once the Smush translation file has been added to your site and you have changed your site language in your WordPress Admin Settings, Smush should fully reflect the new Active Translation language.

Usage Tracking

Usage tracking is incredibly useful for our designers, and enables us to learn more about what features you use and don’t use. It is a completely anonymous feature, and helps us deliver more relevant features in the future.

To enable usage tracking, toggle on Allow usage tracking and click Save Changes.

To enable usage tracking, toggle on Allow usage tracking and click Save Changes.

8.9.2 Configs

Link to chapter 9

The Configs module allows you to save your Smush configurations so that they can be applied to another site in just a few clicks.

To help you get started, we provide a Basic Config denoted with a blue checkmark. It includes the recommended settings that are ideal for fresh installations.

Smush Basic Config

Save a Configuration

To save your current configuration, click Save Config.

To save your current configuration, click Save Config.

Then, enter a name and optional description for the configuration and click Save.

Then, enter a name and optional description for the configuration and click Save.

Saved configurations are listed alphabetically. To view details about a saved configuration, click the configuration in the list.

To view details about a saved configuration, click the configuration in the list.

To make changes to a saved configuration, click the gear icon. The available actions are:

  • Apply – Apply the saved configuration to this Smush installation.
  • Download – Download the saved configuration as a .json file.
  • Name & Description – Edit the name and description for the saved configuration.
  • Delete – Permanently delete the saved configuration.

Additional Configs actions

Upload a Configuration

To upload a configuration that you’ve downloaded from another site, click Upload, and select the relevant .json file from your computer.

To upload a configuration that you’ve downloaded from another site, click Upload, and select the relevant .json file from your computer.

Smush will import the uploaded configuration and add it to the Preset Configs list.

Apply a Configuration

To apply a saved configuration to your Smush installation, click Apply.

To apply a saved configuration to your Smush installation, click Apply.

You will be asked to confirm that you would like to replace your current settings with the saved configuration. Click Apply to proceed.

You will be asked to confirm that you would like to replace your current settings with the saved configuration. Click Apply to proceed.

Sync with the Hub

Smush configurations will automatically be synced with the Hub. Synced configs can be accessed and applied directly from the Config or Security modules in the Hub, or from the Smush installation of any of your sites.

If a new config created in the Hub doesn’t appear immediately in the Smush Settings module, click Check again to refresh your data.

Sync button


This feature is only available to users with the WPMU DEV Dashboard plugin and an active WPMU DEV subscription.

8.9.3 Permissions

Link to chapter 9

This setting applies only to WordPress multisite installations.

Subsites will inherit network settings by default, but the Subsite Controls feature allows you to grant subsite administrators the ability to override modules. You can choose to give subsite administrators any of the following permissions:

  • None
  • All
  • Custom


Select None to force subsites to inherit all network settings. Subsite administrators will not have access to any of the Smush module settings.

Select None to force subsites to inherit all network settings. Subsite administrators will not have access to any of the Smush module settings.


Select All to to give subsite administrators the ability to override all Smush module settings.

Select All to to give subsite administrators the ability to override all Smush module settings.


Select Custom to give subsite administrators the ability to override settings for select Smush modules.

Select Custom to give subsite administrators the ability to override settings for select Smush modules.

8.9.4 Data & Settings

Link to chapter 9

Restore Images

The bulk restore tool can be used to restore your thumbnails to their original state, which is helpful if you’ve made a mistake and need to regenerate your images. Read our Tools documentation for a quick guide to the bulk restore tool.

The bulk restore tool can be used to restore your thumbnails to their original state, which is helpful if you’ve made a mistake and need to regenerate your images.


Choose how your data should be handled if Smush is uninstalled. Select Keep to save your settings upon uninstallation, which will allow them to be restored if Smush is reinstalled. Alternatively, you can select Delete, which will wipe your current settings upon uninstallation.

Select Keep to save your settings upon uninstallation

Click Save Changes to save your changes.

Reset Factory Settings

To immediately restore Smush to its default settings, click Reset Settings.

To immediately restore Smush to its default settings, click Reset Settings.

API Status

Your API key is linked to your WPMU DEV membership account and is important for granting you access to many of the features offered. If you are having issues with accessing pro features, you can force update your API key to update your membership status. Click Update API Status to action this update.

update API status

8.9.5 Accessibility

Link to chapter 9

Color Accessibility

Color accessibility will improve the visibility of elements as per the Web Content Accessibility Guide requirements, up to level AAA which is the highest level of compliance. Toggle on Enable high contrast mode and click Update Settings to activate this mode.

Toggle on Enable high contrast mode and click Update Settings to activate this mode.

This module gives you direct access to Smush tutorials that may be extremely beneficial in helping you get the most out of the plugin. Click on any of the articles to read the full blog or click on the View All button to jump to our complete Tutorial blog page.


8.11 Optimization Guide

Copy chapter anchor to clipboard

About Your Google PageSpeed Insights Score

This chapter guides you through the configuration options for optimizing images with Smush Pro to improve performance based on the image recommendations from the Google PageSpeed Insights scan.

Looking to optimize your file and code assets? See our Hummingbird Optimization Guide.

There are many variables when running a PageSpeed test on a real-world website, and it’s important to understand that not every site can expect a score of 100.

Ads, scripts, and network conditions will cause results to vary for each visit. It is important to note that some very valid tools, such as anti-virus scanners, complex extensions, programs that impact page load or inconsistent ad behavior, can all impact PageSpeed scores. In fact, we recommend that anti-virus scanners and any program known to interfere with pagespeed be disabled during PageSpeed tests.

Google PageSpeed score

The following are some general guidelines regarding Google PageSpeed scores:

  • 0 to 49 is considered slow
  • 50 to 89 is good or average
  • 90 to 100 is fast

For context, a website with a score of 100 is in the 98th percentile of the million top-performing sites. A site with a score of 50 is in the 75th percentile, which is still quite good relative to the vast majority of websites.

So what should your performance success metric be? A realistic PageSpeed score expectation for your website must take into account your host’s servers, content location, the number scripts or third-party calls your page is making, and the plugins and theme you are running.

8.11.1 Properly size images

Link to chapter 11

This recommendation occurs when one or more of the images on the page is incorrectly sized for the container in which it appears.

Google PageSpeed Properly size image metric

The Google PageSpeed test compares the size of the rendered image– that is, the image as it appears on users’ screens– against the size of the actual image– that is, the size of the image being served. If the rendered image is 25KB or more smaller than the actual image, it fails the audit.

To properly size images with Smush, activate the Smush Pro CDN and enable the Automatic Resizing option.

enable automatic resizing

Automatic Resizing creates additional size variations on your CDN based on common screen sizes, filling in the gaps left by the default WordPress-generated thumbnails and uses the srcset attribute to serve the image closest in size to the size of its container.

This method will successfully resolve the Properly resize images audit on any theme that is properly utilizing the image sizes feature.

Page builder considerations

In an attempt to give users more freedom, page builders use various methods to size and resize images. This freedom comes at the cost of resources, and images may have to be manually resized to fit their containers.

If you are using a page builder or have activated the image CDN and consistently still fail the “Properly size images” audit, you can locate the images with Wrong Size Detection and choose the appropriate thumbnail if it is included in the list of generated images.

If the size you need is not available, you will need to provide a new image in the correct size in order to pass the audit.

To enable the Wrong Size Detection feature in Smush Pro, go to plugin settings, and in the image Resizing section, enable Detect and show incorrectly sized images. Then save your settings.

Smush pro image resize detection

This setting will highlight incorrectly sized images for the admin. Use the information tab (yellow “i” icon) to see what size to scale the image.

Image resize feature Smush Pro

Watch our instructional video to see how the Smush wrong size detection feature works.

If you need to scale your images manually, we have written an in-depth tutorial for properly resizing and serving scaled images with WordPress.


Automated image scaling with the CDN may not work well for images on themes or page builders that do not use the srcset attribute to define images.

8.11.2 Defer offscreen images

Link to chapter 11

This audit lists all offscreen or hidden images on your page along with the potential savings in kilobytes. Use the Smush Lazy Load feature to defer your offscreen images from loading until they are needed.

Google PageSpeed Defer Offscreen images

To activate lazy loading with Smush Pro, click the Lazy Loading option in the Smush dashboard and click the Activate button.

Select image types to lazy load

Watch our instructional video to see how the Smush lazy loading feature works.

This feature stops offscreen images from loading until a visitor scrolls to them, making your pages load faster, uses less bandwidth, and fixes the failed “defer offscreen images” audit.

The default settings work well for most sites. But keep in mind the audit is only for images located offscreen so it is a good idea to exclude any images in the viewport. Smush Pro Lazy Loading gives you controls for excluding file types, output locations, animation speed, and pages you may want to exclude.


Do not use the Smush Pro Lazy Load feature if you have lazy loading active with another plugin or it is built-in to your theme or page builder. Having the same function active in multiple plugins can cause a conflict that makes your images appear broken.

If you are looking for more information about manually implementing Lazy Load on your site, visit the How to Defer Offscreen Images guide on our blog.

8.11.3 Efficiently encode images

Link to chapter 11

This is a list of all unoptimized images, with potential savings in kilobytes. To check if your images are correctly encoded, Google’s PageSpeed test collects all the JPEG or BMP images on the page, sets each image’s compression level to 85, and compares the original version with the compressed version. If the potential savings are 4KB or higher, the images will fail the audit.

Google PageSpeed efficiently encode images metric

To resolve this with Smush Pro, use the Bulk Smush Automatic Compression setting to automatically web optimize your images on upload.

enable automatic compression

If you already have images in your media library when installing Smush, use Bulk Smush to optimize any existing images.

Bulk Smush all images

To optimize images up to 2x more than the default Smush option with multi-pass lossy compression activate Super-Smush.

Super Smush images

Remember to click Save whenever making changes to Smush settings. Run Bulk Smush to apply changes to any existing image files.

8.11.4 Serve images in next-gen formats

Link to chapter 11

Next-gen image formats are modern image formats with superior compression capabilities. WebP is the leanest and typically achieves 30% more compression than JPEG and JPEG 2000.

Google PageSpeed next-gen image metric

Smush Pro can be used to serve images in the WebP next-gen format for supported browsers. If the browser does not support WebP, Smush will use the original image format as a fallback.

There are 2 options for serving WebP images with Smush Pro:

  • Using the feature built into the Smush CDN
  • Using the Local WebP feature

WebP with Smush CDN

The feature is active by default once the Smush CDN is enabled.

You can check to see if it is activated in Smush Pro under the CDN menu item. Scroll to WebP Conversion and toggle Enable WebP conversion.

Enable WebP conversion in Smush

Watch our instructional video to see how to serve images in WebP format.

Click the Update Settings button to save your changes.

To learn how to manually convert images into a WebP format and set up fallback images with srcset, follow our guide for serving images in next-gen formats.

You can verify your images are being served in a next-gen format on your support browser using the Chrome inspect tool. Right-click on an image, choose inspect and check that the link uses the WebP extension.

Inspect image for webp format

Local WebP option

If you do not wish to use the Smush CDN, you can instead opt to enable the Local WebP feature in Smush Pro.

Once enabled and configured according to your server type, you’d need to run the Bulk Smush feature again to generate a .webp version of every image. Those new .webp images are stored in a new /smush-webp/ folder on your server.

Any time an image is requested by the browser, Smush will check that folder and, if the .webp version exists, it will be served to browsers that support that format. Otherwise, your original .jpg or .png image will be served.

For more info on the Local WebP feature, and how to configure it for your site, see the Smush Pro > WebP documentation.


Remember to clear your cache after making changes and give time for the image changes to complete before running a new PageSpeed test.

After reading this guide, if you still have questions regarding Smush, don’t hesitate to start a live chat with our support Superheroes or submit a support ticket using the Support tab of your WPMU DEV Dashboard.

new support ticket