8. Smush

The Bulk Smush Settings are your primary optimization tools and they apply only to Bulk Smush and thus to images in your Media Library only.

Smush Mode

You can customize the level of compression you need for the images with Smush mode. There are three levels of compression:

Basic – With lossless compression, this method provides pixel-perfect images with minimal file size reduction. Your visuals will remain clear without any compromise in performance

Super – The lossy compression of super mode offers much better compression and file size reduction than basic mode without compromising the image quality. The reduced file size provides better performance and load speed.

Ultra – The Ultra mode offers a professional-level image compression that is 5 times greater than the Super mode. It can reduce file sizes significantly while maintaining impressive image quality. This is a pro feature and requires an upgrade to Smush Pro.

Image Sizes

The Image Sizes feature allows you 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.

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.

WordPress.com users

If your site is hosted on either a Business or an eCommerce plan at wordpress.com, 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 wordpress.com’s own CDN and Smush cannot fetch them to optimize them for you.

You will see a notice like this when that Jetpack feature is enabled:

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 to your Media Library, regardless of the method used to upload them: through the media library uploader, through WordPress or WooCommerce Rest API, or via WordPress mobile apps.

Please note that if an image is larger than 32 Mb, it will not be compressed automatically, even if the automatic compression feature is enabled. We suggest manually compressing any images that exceed 32 Mb in size.

Original Images

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

To save a copy of your original images, enable Backup original images. If enabled, keep in mind that saving a copy of original images can significantly increase the size of your uploads folder. See also Bulk Restore below for important information.

Metadata

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.

Advanced Settings

Click on the Advanced Settings heading to reveal additional options.

Image Resizing

WordPress automatically creates a scaled version of the uploaded images larger than 2560x2560px and keeps the originally uploaded images as a backup. Using image resizing options, you can modify the default resizing threshold and disable the creation of scaled images.

Resize uploaded images – This option lets you change the default max width and height threshold defined by WordPress to other dimensions.

Disable scaled images – Enabling this option completely disables the scaling functionality. When enabled, WordPress will no longer create scaled versions of the uploaded images, regardless of their size. This option ensures that the originally uploaded images are retained without any automatic resizing.

For example, If the dimensions of the original image are 4000x4000px and if only the Resize original images option is enabled with max width and height values set to 3000x3000px, the original image is backed up, a scaled version is created, and the scaled version is then resized to 3000x3000px.

If only the Disabled scaled images option is enabled, no automatic resizing of the uploaded images occurs, and the original image is retained as is.

If both options are enabled, the original image will be resized to the set threshold value (3000x3000px in our example).

Did you know that GTMetrix recommends Smush for image optimization and resizing?

PNG to JPEG Conversion (Smush Pro only)

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

In this process, the original PNG file will be deleted. However, you can retain the original PNG file as a backup by enabling the backup original images option.

Email Notification (Smush Pro only)

Enable this option to have an email sent to your admin email address when the bulk smush process completes in the background.

Bulk Restore

The Bulk Restore feature can only be used to restore 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.

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.

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

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

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.

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.

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

Use the Smush filter to display all images, just those that were ignored, those not yet processed or those for which processing failed.

Note that 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 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 when running Bulk Smush by clicking the Ignore link.

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

If you had already Smushed your images with Basic or Super smush mode, then enabled Ultra Smush afterwards, click the Ultra Smush link to get even more savings for those already processed images.

Any image that was processed after the Backup Original Images option was enabled can be restored by clicking the Restore link that appears for those images. See below for help restoring images that were not backed up.

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.

If you are using the Next-Gen Formats feature to create WebP or AVIF versions of your uploaded images, you’ll see additional information beneath the default Smush stats that display the image size reductions for the selected next-gen format.

Restoring Images

If you had optimized images before enabling Backup Original Images, and need to restore the originals and/or the thumbnails, you have a couple of options.

Restore the Original Image and its Thumbnails

You can restore the original image manually by re-uploading it to your media library. Then run Bulk Smush to optimize the thumbnails.

If the image was attached to a post or used somewhere else on your site, you will of course need to manually update that post or site element with the newly uploaded image as well.

Restore Just the Thumbnails

Smush can Bulk Restore all thumbnails of all images if the Backup Original Images option was already enabled. But it does not have an option to restore thumbnails for single images, whether that option was enabled or not.

So you would need to use a 3rd-party solution like the Regenerate Thumbnails Advanced plugin where you can choose the image(s)for which thumbnails should be restored.

Note however that if you had enabled the Compress original images option in Smush, that 3rd-party plugin would still use the compressed original as its source. Consequently, the quality of the regenerated thumbnails will be impacted. In this case, you may wish to opt for the manual solution above.

Skip Selected Folders

By default, Bulk Smush will process all images in your /uploads directory.

If there are one or more folders in that directory that you do not want Bulk Smush to process, you can use this filter in a mu-plugin.

Edit the $excluded_paths array to specify the folders you want the process to ignore.

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.

Media Types

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

Embedded Content

If you have content embedded on your pages via iframes, enable this option to lazy-load those iframes. Once enabled, you can also choose to replace YouTube or Vimeo iframes with preview images. The videos themselves will only load when their play buttons are clicked.

This can help to significantly improve your page speed scores for the following audits:

• Some third-party resources can be lazy loaded with a facade
• Reduce JavaScript execution time
• Reduce the impact of third-party code
• Reduce unused JavaScript
• Reduce unused CSS
• Does not use passive listeners to improve scrolling performance
• Avoid serving legacy JavaScript to modern browsers
• Avoid long main-thread tasks (desktop)

Using Custom Preview Images

Smush will use the most appropriate size of any default preview images provided by YouTube or Vimeo for your embedded video. However, if you wish to use a custom image instead (in jpg or png format), you can specify that by including the following attribute in the iframe code when adding it to your page or post:

data-poster="https://full-url-to-your-image.jpg"

You can also use this same attribute to load a preview image if the video does not have any thumbnail set.

Embedding Playlists and Showcases

There is no default way to lazy load and display a preview image for YouTube playlists or Vimeo showcases/albums. However, by using the following filters in your active child-theme’s functions.php file or a mu-plugin, you can get that done.

Vimeo

To lazy load Vimeo showcases with a preview image of the first video, add both of the following filters as they are with no modifications.

YouTube

To lazy load YouTube playlists with a preview image of any video in each playlist, use the following filter. Replace PLAYLIST_ID_HERE with only the ID of the playlist you’re embedding, and replace VIDEO_ID_HERE with the ID of the video whose thumbnail image you want to use as the lazy loaded preview image. You can include as many playlists as needed in the filter by adding a new line in the $map_playlist_ids array.

Output locations

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

Image Sizing (Smush Pro only)

The options here help Smush to serve the correct image size to browsers in every situation.

Enable automatic resizing of my images

Enabling this option will eliminate the “Properly size images” PageSpeed warning by dynamically resizing images to perfectly fit their containers, regardless of their original size.

Add missing dimensions

Enabling this option will automatically add any missing image dimension attributes to speed up rendering and reduce layout shifts. This resolves the PageSpeed Insights “Ensure images have explicit width and height” recommendation.

How Automatic Resizing Works

By default, 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 1280px wide, the max-width that will be served is 1000px because that’s what is defined in the theme for the content_width.

When the automatic resizing option is enabled, the values of the original sizes attribute are delivered in a new data-original-sizes attribute, with the sizes attribute now specifying the exact size of the image to be dynamically served to the browser according to the viewport size. When this is combined with the Dynamic Image Sizing feature in the Smush CDN, you’ll also see that additional size in the srcset so you’ll know it will perfectly fit the image container.

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 Bulk 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.

Advanced Settings

Click on the Advanced Settings heading to reveal additional options.

Exclusions

By default, lazy loading is enabled for all content. Here, you can define post types, specific pages and posts, as well as specific images that you want to exclude.

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.

Custom Exclusions

Here, you can define specific items that you want to be excluded from lazy loading.

Posts, Pages & URLs

You can disable lazy loading for all images or iframes on any posts, pages or URLs by entering the URLs in the Posts, Pages & URLs field, one URL per line.

Classes & IDs

Here, you can exclude specific images or iframes by specifying any classes, IDs, attributes, keywords or strings of characters from the image or iframe codes, one entry per line.

For example, specifying any of the following from the image code below would exclude the image from lazy loading:
wp-image-10248
cat-
3 kittens
2021/05

<img decoding="async" src="https://example.com/wp-content/uploads/2021/05/cat-3535404-1000x667.jpg" alt="3 kittens" class="wp-image-10248" title="3 kittens title">

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.

Spinner

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.

Placeholder

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.

Scripts

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.

Native lazy load

Click the Enable native lazy loading toggle to enable support for native browser 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.

Noscript Tag

Enabling this option provides a fallback mechanism to lazy-load images in browsers that do not support javascript. However, if you are using W3C’s validation tool, or are perhaps using image transitions triggered via javascript, you may experience issues if NoScript is enabled on your pages. In such cases, you might want to leave this option disabled.

Deactivate

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

Lazy Loading Filters

Exclude Attributes from Lazy Loading

Images that have certain attributes may conflict with Lazy loading. To ensure compatibility, images with such attributes are excluded from the lazy loading process.

Images with the following attributes will be excluded from lazy load by default.

However, if you wish to exclude any attribute other than those mentioned above from lazy load, for example data-skip-lazyload, you can use the following filter.

Change data-skip-lazyload in the following code to the correct attribute if different.

Disable Lazy Loading for Selected Images

This filter only applies if you have enabled the Lazy Load feature in Smush.

There may be times when you wish to exclude one or more images from lazy loading. For example, any images resting above the fold.

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

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 lazy loading, use this code and adjust the image URL:

Exclude Multiple Images

To exclude multiple images from lazy loading, 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).

Skip all image URLs that contain /preloader.png

Lazy Loading Images from URLs without Extension

To lazy load images from URLs without extensions, add the following filter. Note that this filter currently supports images from gravatar.com or googleusercontent.com. To support images from other sources, change the regex accordingly.

Preloading critical images helps improve your site’s Largest Contentful Paint (LCP) score by prioritizing the loading of the largest image in the viewport. Since LCP measures the time it takes for the largest visible element on a page to load, optimizing it is essential for achieving a better PageSpeed score and a smoother user experience.

Smush will automatically detect and preload the largest image above the fold to help meet Google’s recommended 2.5-second LCP benchmark. Additionally, the fetchpriority="high" attribute will be automatically added to every LCP <img element to ensure they are not lazy loaded.

Click the Enable Preloading Critical Images toggle to activate the feature if you haven’t already.

Exclude

If there are any pages, posts or URLs where you need to prevent image preloading, enter their relative URLs in the field provided, one per line. This can be especially useful if LCP images are changed dynamically on a page. This option only appears once the feature is active.

Clear LCP Data

Use this option to clear all LCP preload data from your site if needed. For example, if you’ve made image optimisations and want to ensure Smush identifies new critical images.

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.

Upgrades

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

• Free – 0
• Basic – 5GB
• Standard – 10GB
• Plus – 20GB
• Premium – 50GB

All hosting-only plans include 10GB of Smush CDN bandwidth.

More CDN bandwidth can be purchased as needed, from 50GB/mo to 10TB/mo, and your Smush CDN bandwidth plan can be upgraded or downgraded at any time.

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

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

Use a Different Attribute for Images in Content

By default, the WPMU DEV CDN will use the following list of attributes of your images to serve them to the browser.

• href
• data-href
• src
• data-src
• srcset
• data-srcset
• data-thumb
• data-thumbnail
• data-back
• data-lazyload
• data-bg
• data-bg-image
• data-settings (as used in Elementor sliders)

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.

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:
smush_skip_image_from_cdn

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.

Here are a few examples for using this filter:

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).

Exclude a Single Background Image

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

Exclude Multiple Background Images

To exclude multiple background 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).

Exclude Images by Post Type

To exclude images on all single posts of a specified post_type, use this code and change post on line 5 to the post_type you wish to exclude.

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

Serve Image in a Custom Directory

By default, the WPMU DEV CDN serves images located in the wp-content directory. However, you can use the following filter to serve images stored in a custom uploads directory outside the default wp-content folder via the CDN. Change the directory URL in this code to the actual uploads directory on your site.

When you select the WebP format, you’ll have the option to use a Direct Conversion method which requires no configuration, or a Server Configuration method; see the next chapter for details on that method.

Selecting the Direct Conversion method will serve WebP images to browsers that support this format without requiring a CDN or any server setup.

When the Direct Conversion method is enabled, an option to Enable JavaScript Fallback will appear. Enabling this option will ensure that the original JPEG/PNG images (without WebP conversion) will be served to browsers that don’t support WebP.

If the Direct Conversion method above does not work for your project, or if you prefer setting things up directly on your server, choose the Server Configuration method.

This method will search for your next-gen format images inside the /smush-webp/ folder and serve them to your site. If there’s no WebP file for a specific image, or if the browser does not support that format, the original JPEG/PNG will be served automatically.

On WPMU DEV hosted sites, the server configuration will be handled automatically for you. If your site is hosted by a 3rd-party, follow the Server Setup steps below.

Server Setup

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.

If your server is running NGINX as a proxy for Apache, see Proxy / Hybrid Setups below.

If your site is hosted on a Bitnami instance, see Bitnami Setups below.

Note that Windows IIS servers are not supported for Local WebP; consider using the CDN WebP option instead.

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. Also see Adding Rules Manually below.

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

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.

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.

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.

Adding Rules Manually

As seen in the Server Configuration Method chapter above, you’ll need to add rules manually if your server type is Nginx or Bitnami, or if the automatic method doesn’t work for you on your Apache server.

For both Apache and Nginx, the Setup Wizard will display the default rules you need for your specific install.

Apache

Add these rules to the .htaccess file in the root directory of your site (usually public_html).

If your WordPress is installed in a subdirectory and the site URL includes that subdirectory (like domain.com/wordpress), you do not need to change anything in these rules. However, you may need to add them to a .htaccess file in the wp-content/uploads directory instead of the root. Try the file in the root directory first, and if it doesn’t work there, move them to the file in the /uploads directory.

If your WordPress is installed in a subdirectory and the site URL does not include that subdirectory (loads at domain.com), see WordPress in its Own Directory below.

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

Nginx

Before adding these rules to your nginx.conf file, be sure to adjust the path to the wp-content directory as shown on line 5 of the code below. You’ll find the correct path for your install in your site’s wp-admin under Tools > Site Health > Info > Directories & Sizes.

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

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.

Bitnami Setups

Bitnami doesn’t allow overriding the htaccess rules in the local .htaccess file, so the setup is a bit different in this type of installation.

You’ll first want to locate your wordpress-htaccess.conf file, which can be found in the /opt/bitnami/apache/conf/vhosts/htaccess/ directory.

Then add the following rules in that file:

Check the file paths to make sure they are correct, then save the file and restart the Apache server using this command: sudo /opt/bitnami/ctlscript.sh restart apache

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

If the status message in Smush indicates WebP is still not working, try changing <IfModule mod_headers.c> in the rules above to <IfModule mod_headers>

WordPress in its Own Directory

When you install WordPress in its own directory (like domain.com/wordpress), but have it load at the root domain (domain.com), 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.

Apache/Litespeed

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]

NGINX

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

Selecting the AVIF next-gen format will serve AVIF images to browsers that support this format without requiring a CDN or any other configuration.

When this format is selected, an option to Enable JavaScript Fallback will appear. Enabling this option will ensure that the original JPEG/PNG images (without AVIF conversion) will be served to browsers that don’t support AVIF.

Once the setup has been completed, a success message will be displayed with a reminder to run Bulk Smush to get local WebP/AVIF versions of all your existing images created. Images uploaded after the setup has been completed will be automatically converted to your selected format.

Revert Next-Gen Formats Conversion

If you need to delete the next-gen 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 the WebP or AVIF files from your server, click the Delete WebP/AVIF Files button. Your images will fall back to normal PNGs or JPEGs once the next-gen files are deleted.

Note that this option will only delete image files created by the Next-Gen Formats module, and will not delete any next-gen files served by the Smush CDN.

Deactivate

To deactivate the Next-Gen Formats module, click Deactivate. Your original JPEG/PNG images will then be served instead of the next-gen images.

The deactivation process will also create a disable_smush_[format] file inside the /smush-[format]/ directory created when you configured the feature. As long as this file exists, your original JPEG/PNG images will be served. If you re-enable Next-Gen Formats, the disable_smush_[format] file will be deleted and WebP/AVIF images will be served again without issue.

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

To check that your images are indeed being served in the selected next-gen format, you can simply check a page’s source code to see if images are being served from the /smush-[format]/ directory and have a .webp or .avif extension appended to their filenames, like this example:
https://coolsite.tld/wp-content/smush-avif/2025/02/image-1000x563.jpg.avif

Alternatively, you can 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” or “content-type: image/avif” there, that tells you that the browser is indeed serving up the selected next-gen version of the image.

Sometimes, a browser may fail to identify the exact content type of an image due to changes in the image URL. This can lead to a bit of odd behavior.

As illustrated in the image below, the final image extension is .avif, but the image type mentioned in the Content-Type field is jpeg.

In such cases, you can rely on the file extension to confirm that everything is functioning properly and ignore the image type shown in your browser’s response headers.

Note that if the Amazon S3 Integration is active in Smush Pro > Integrations below, images that are offloaded to AWS will not be served in next-gen formats with this module. Only locally stored images will be served in next-gen formats.

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.

If this is enabled, when you view your site on the front end, you will notice an Image Issues section in your right 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.

Translations

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

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. See our Privacy documentation for more information about the data we collect.

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

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 Default config denoted with a blue checkmark. It includes the recommended settings that are ideal for fresh installations.

Save a Configuration

To save your current configuration, click Save Config.

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 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.

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.

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.

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.

Settings and Options Stored in Configs

In the list below, you’ll find a breakdown of all settings and their available options included in the config file:

Bulk Smush

• Smush Mode: Basic | Super | Ultra (Single value is stored)
• Image Sizes: All | Custom (Single value is stored)
• Automatic compression: Active/Inactive
• Metadata: Active/Inactive
• Image Resizing – Resize original images: Active/Inactive
• Image Resizing – Disable scaled images: Active/Inactive
• Original Images – Optimize original images: Active/Inactive
• Original Images – Backup original images: Active/Inactive
• PNG to JPEG Conversion: Active/Inactive
• Email Notification: Active/Inactive

Lazy Load

• Media Types: .jpeg | .png | .webp | .gif | .svg (Multiple values can be stored)
• Embedded Content: Active/Inactive
• Output Locations: Contents | Widgets | Post Thumbnails | Gravatars (Multiple values can be stored)
• Auto Resizing: Active/Inactive
• Add Missing Image Dimensions: Active/Inactive
• Display & Animation: Fade in | Spinner | Placeholder | None (Single value is stored)
• Include/Exclude Post Types: Frontpage | Blog | Pages | Posts | Archives | Categories | Tags (Multiple values can be stored)
• Scripts: Header | Footer (Single value is stored)
• Native lazy load: Active/Inactive
• Noscript Tag: Active/Inactive

Preload

• Preload Critical Images: Active/Inactive

CDN

• Supported Media Types: JPG | PNG | WEBP | GIF (Multiple values are stored)
• Background Images: Active/Inactive
• Dynamic Image Sizing: Active/Inactive
• Next-Gen Conversion: WebP | AVIF | None (Single value is stored)
• REST API: Active/Inactive

Next-Gen Formats

• Next-Gen Formats: WebP | AVIF (Single value is stored)

Integrations

• Gutenberg Support: Active/Inactive
• Gravity Forms: Active/Inactive
• WPBakery Page Builder: Active/Inactive
• Amazon S3: Active/Inactive
• NextGen Gallery: Active/Inactive

Settings

• Image Resize Detection: Active/Inactive
• Usage Tracking: Active/Inactive
• Keep Data on Uninstall: Active/Inactive
• Color Accessibility: Active/Inactive

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

None

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

All

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

Custom

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

Uninstallation

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.

Click Save Changes to save your changes.

Reset Factory 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.

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.

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

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.

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.

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.

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.

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.

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

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.

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.

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.

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

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

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

Next-gen image formats are modern image formats with superior compression capabilities. WebP typically achieves 26-30% smaller file sizes than JPEG or PNG, and AVIF images are up to 60% smaller than comparable JPEG or PNG images

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

There are 2 options for serving next-gen images with Smush Pro. See the linked chapters for more information on each option:

• Using the Next-Gen Conversion feature built into the Smush CDN
• Using the local Next-Gen Formats feature