8. Smush

The header bar is displayed across all screens in Smush and provides quick access to key tools and resources.

Click WPMU DEV to navigate to The Hub, your central dashboard for managing all your WPMU DEV-connected sites. You’ll be welcomed by a short tour of the main Hub features.

From the header bar, you can also quickly access WPMU DEV support and this usage guide.

You can also open the Activity Log sidebar, which displays a timestamped record of all actions performed in Smush. The icon appears in green when there is new activity, and turns grey once you have viewed all activity.

Click your profile picture to access a menu with links to Support, Documentation, and the Product Roadmap.

If your site is connected to a free WPMU DEV account, an additional Disconnect option appears in the menu, allowing you to disconnect your site from the account.

If your site is not yet connected to a WPMU DEV account, a crossed-out profile icon appears in its place. Clicking it prompts you to connect by either creating a free account or signing into an existing one.

The Media library panel allows you to take action on your images directly from the Dashboard.

Scan Site

You can trigger an immediate scan of your image library at any time by clicking the Scan site button. The date and time of the last scan is displayed next to the button for reference.

While the scan is in progress, a progress bar appears in the bottom-right corner of the screen showing the current scanning status.

Once the scan is complete, a notification appears in the top-right corner displaying the number of images ready to optimize. Click Optimize Images to begin optimizing immediately, or Not Now to dismiss the notification.

Upload

Click Upload to navigate to the WordPress Media Library, where you can add new images to your site. Smush also adds several features to the Media Library to help you manage and optimize your images directly from there. See the Media Library section for details.

Select Compression

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.

Backup 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 Restore All Images below for important information.

Note that this option is enabled by default on new installs or when you reset Smush settings.

Optimize Images

Click Optimize Images to begin optimizing all uncompressed images in your Media Library. Smush will apply the compression level and settings you have selected to all images that have not yet been optimized.

While optimization is in progress, the Optimize Images button is replaced by a progress bar showing the percentage of completion. A notice below the progress bar confirms that processing continues in the background, meaning you can navigate away from the screen without interrupting the process. If you navigate to any other Smush screen, the progress bar moves to the bottom-right corner of the screen.

To stop the optimization process, click the Stop button. A confirmation modal will appear asking you to confirm. Click Stop Optimizing to terminate the process, or Resume to continue optimizing.

Once all images have been optimized, a notification appears in the top-right corner of the screen confirming the total number of images optimized and the amount of storage saved. Click OK to dismiss the notification.

Image Size Limits

The Optimize Images feature allows you to apply all your enabled features to any uncompressed images in your Media Library with a single click. The Pro version allows you to optimize images up to 256Mb/image, while the free version allows a maximum of 5Mb/image.

Please note that although the image optimization limit for the pro version is 256 Mb, we advise not to get too liberal with adding large images. Doing so may affect the site’s performance, regardless of the allowed limits.

Multisite Networks

Note that, on WordPress Multisite networks, image optimization is not available by default and needs to be enabled in the Network Admin under Smush > Settings > Permissions. Once it has been enabled, Smush will be available on the subsites.

What does Smush Compress?

Smush will only compress images in the Media Library. If the images are in a different location (e.g., a plugin folder), then Directory Smush can be used. However, the same rules below apply.

• images must be under 256Mb if using Smush Pro (5Mb in Smush free);
• images must be in .jpeg /.jpg or .png format (transparent .png images can be compressed but will not be converted to .jpeg),
• images will only be compressed if the result would be an image with a smaller file size.

What does Smush NOT compress?

• any image format that is not .jpeg /.jpg or .png,
• images with ‘missing headers’ (typically a corrupt or badly saved image),
• document, video, audio files (e.g., .pdf, .avi, .mp3, .mp4).

How are images optimized?

The Smush API sends your images via HTTPS to secure 3rd-party servers where they are compressed by writing temporary files to disk. The optimized images are returned to your server and temporary files are deleted immediately. There is no local or intermediate storage which eliminates the possibility of your images being accessed by unauthorized parties during the process.

Parallel Processing

Smush works on optimizing all the default WordPress image sizes for a media item in parallel, which makes the image optimization process much faster.

Parallel processing requires the curl_multi_exec() function to be enabled on your server. If your hosting provider has disabled that function, Smush will fall back to processing images sequentially.

If that function is enabled on your server, but you wish to disable the parallel optimization feature and optimize images sequentially instead, add the following constant to your wp-config.php file, just before the line that says “That’s all, stop editing“:

define ( 'WP_SMUSH_PARALLEL', false );

Background Processing

Smush processes your images in the background, so you need not keep the Dashboard screen open while it’s working.

You can optionally receive an email, at the admin address that is set under Settings > General in your wp-admin, when the process is complete.

Note that if you have enabled the White Label option in the WPMU DEV Dashboard plugin, this email will also be fully white labeled with no mention of WPMU DEV.

Cancel Optimizing Images

To stop the optimization process, click the Stop button on the progress bar and confirm by clicking Stop Optimizing in the modal window that appears.

If clicking Stop Optimizing does not stop the process, you can force it to stop by pasting this URL in your browser and refreshing the page. Change yoursite.tld to your actual domain name.

https://yoursite.tld/?wp_smush_stop_background_processing=1

If that still does not stop the process, you can try either of the following two code options. Remember to remove the code afterwards or you will not be able to run image optimization at all.

• Add this constant to your wp-config.php file, just above the line that says “That’s all, stop editing“:

  define('WP_SMUSH_STOP_BACKGROUND_PROCESSING', true);

• Or add this filter to your child-theme functions.php or a mu-plugin:

Smush Savings

The Smush Savings panel displays a real-time summary of your image optimization results. It shows the total amount of storage saved across all optimized images, the number of images remaining to optimize, and the number of images already optimized.

Smush Filters

Skip Selected Folders

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

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

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

The Quick Feature Controls section displays cards for key Smush features, giving you a quick way to enable or disable each feature directly from the Dashboard. Each card includes a brief description of the feature along with a Learn more link that takes you to the feature’s configuration screen where you can manage its settings in detail.

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 Load, navigate to the Lazy Load & Preload screen in the Smush menu and toggle on the Lazy Load option at the top of the screen.

Areas to Lazy Load

You can choose where lazy loading is applied using the Areas to Lazy Load setting. Enable the All areas toggle to apply lazy loading across all available locations at once, or click individual locations to enable or disable them selectively.

Media Types to Lazy Load

Use the All media types toggle to include or exclude all supported media types at once.

You can also click individual media types to include or exclude them from lazy loading.

When the .iframe media type is selected, iframe content embedded on your pages will be lazy-loaded.

Once iframe lazy loading is enabled, you can optionally enable YouTube / Vimeo preview images to replace embedded YouTube or Vimeo iframes with preview images. When this option is enabled, the video iframe is only loaded when the play button is clicked, helping improve page load performance on pages with embedded videos.

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.

Scripts & NoScript

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 Loading

Click the 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 Fallback

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.

Loading Appearance

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. Select from the available predefined spinners, or click the plus icon to upload a custom spinner.

Placeholder

If you want to display a custom placeholder while images load, choose an icon to display instead of the actual image. You can use the default icon provided or upload your own.

You can also set a background color using the color picker. Alternatively, select None if you don’t want to display a placeholder, in which case containers will remain empty until images are fully loaded.

Exclude Content from Lazy Load

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 URL(S)

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.

Keyword

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

Deactivate

If you no longer want to use the lazy load feature, you can deactivate it at any point by toggling Lazy Load off.

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.

To enable Preload, navigate to the Lazy Load & Preload screen in the Smush menu, select Preload, and toggle on the Preload option at the top of the screen.

Fetchpriority

Enable this option to replace WordPress’s default fetchpriority=”high” attribute with smarter LCP detection. WordPress automatically applies fetchpriority=”high” to the first three images on a page, which can interfere with lazy loading and image handling. This detection method is more accurate and ensures better lazy loading.

Click the Fetchpriority toggle to activate this feature.

Clear LCP Data

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

Exclude Content from Preload

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.

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

• Free – 0
• Basic – 50GB
• Standard – 100GB
• Plus – 250GB
• Premium – 500GB

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

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

The Tools screen brings together the core image optimization settings for Smush, covering everything from automatic optimization and image sizing to large image resizing and image restoration.

General

This panel includes settings that control how images are automatically optimized when they’re uploaded to your site.

Automatic Compression

Click the slider to enable automatic compression, and Smush will optimize 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.

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.

Remove Metadata from 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.

Optimize Original Images

By default, WordPress only optimizes image sizes generated when images are uploaded, not the original uploaded files themselves. To optimize your original images, enable Optimize original images.

Image Sizing (Smush Pro only)

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

Automatic Resizing

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.

Set Image 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 Resizing 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 Large Image Resizing panel. 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.

Image Sizes

The Image Sizes feature lets you choose which thumbnails are compressed and which ones are ignored.

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.

WordPress creates multiple thumbnails for each uploaded image. Use this section to select which image sizes are included when you compress and optimize images in bulk.

Enable the All image sizes toggle to include all available image sizes, or click individual image sizes to select or deselect them.

The image sizes you select will be compressed automatically on upload if Automatic compression is 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 optimize 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.

Large 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 the large image resizing options, you can modify the default resizing threshold and disable the creation of scaled images.

Resize large 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 Disable 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).

Others

PNG to JPEG Conversion

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

Enable this option to receive an email notification at your admin email address when image compression and optimization completes in the background.

Restore All Images

The Restore All Images 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 to start the restoration process.

You will then see a confirmation modal. Click Restore to follow through with the restoration. Alternatively, click Cancel to exit without initiating the restoration.

Once confirmed, the Restore button displays a spinner while the process runs. The modal closes automatically once the restoration is complete.

The Next-Gen Formats feature in Smush Pro enables you to serve images from your Media Library in next-gen WebP or AVIF formats, without relying on the Smush CDN.

Enable the Next-Gen Formats feature by toggling it on from the Next-Gen Formats panel.

Note that this feature only works for images in your Media Library; it cannot create next-gen versions of images located in other directories.

Next-Gen Formats supports JPEG and PNG images from your Media Library.

Once you have configured this feature, you will need to optimize your existing media library images again to get a WebP or AVIF version created for each one.

Depending on the next-gen format you choose, optimizing your images will create a /smush-webp/ or a /smush-avif/ folder in the wp-content directory that replicates the structure of your /uploads/ folder, and will create and store next-gen versions of all your images there.

The conversion to WebP is lossy when converting from JPEG images, and lossless when converting from PNG images. Conversion to AVIF is lossy for both PNG and JPEG images.

If you configure one next-gen format, then switch to a different one, a Require Action notification will appear prompting you to run Smush to apply the change. Click Optimize Images to begin, or dismiss the notification by clicking Not now or the X icon. Make sure to also clear all cache on your site to ensure your images are served correctly.

WebP – Direct Conversion

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 under the Others panel. Enabling this option will ensure that the original JPEG/PNG images (without WebP conversion) will be served to browsers that don’t support WebP.

WebP – Server Configuration

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

• Exclude image extensions from NGINX rules so those files are now served via Apache.
• In Smush, go to the Local WebP page and follow the setup wizard’s guide to add Apache rules.
• 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:

AVIF

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 under the Others panel. Enabling this option will ensure that the original JPEG/PNG images (without AVIF conversion) will be served to browsers that don’t support AVIF.

Revert 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 files button. Your images will fall back to normal PNGs or JPEGs once the next-gen files are deleted.

Deactivate Next-Gen Formats

To deactivate the Next-Gen Formats feature, toggle it off. 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.

Verifying Next-Gen Output

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.

Next-Gen Integrations

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.

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.

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.

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.

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.

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 optimize any images contained in your S3 buckets, significantly reducing your cloud storage usage. This feature works together with Smush’s Automatic Compression feature, so be sure to enable it.

NextGen Gallery (Smush Pro only)

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.

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.

Subsites inherit network settings by default, but the Permissions screen allows you to control which Smush settings subsite administrators can override. 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 setting

Custom

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

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

The first time you navigate to the Config screen, a welcome prompt appears providing a brief overview of what you can do with Smush configurations. Click Got it to dismiss it and proceed, or click the X icon to close it.

To help you get started, we provide a pre-configured Smush Default config that includes the recommended settings ideal for fresh installations.

Save a Configuration

To save your current configuration, click Save New.

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

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

You can edit the configuration name and note by clicking the pencil icon.

To make changes to a saved configuration, use the Action and Info sections.

Under Action, the available options are:

• Apply this config – Apply the saved configuration to this Smush installation.
• Download – Download the saved configuration as a .json file.
• Delete – Permanently delete the saved configuration.

Under Info, you can add or edit a note for the configuration by clicking the pencil icon next to Note. The Date added field displays when the configuration was created.

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 this config under the Actions section.

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:

Dashboard

• Compression Level: Basic | Super | Ultra (Single value is stored)
• Backup Original Images: Active/Inactive

Lazy Load

• Media Types to Lazy Load: .jpeg | .png | .webp | .gif | .svg (Multiple values can be stored)
• Lazy Load for iframes: Active/Inactive
• Areas to Lazy Load: Contents | Widgets | Post Thumbnails | Gravatars (Multiple values can be stored)
• Loading Appearance: Fade in | Spinner | Placeholder | None (Single value is stored)
• Exclude Content from Lazy Load: Frontpage | Blog | Pages | Posts | Archives | Categories | Tags (Multiple values can be stored)
• Scripts: Header | Footer (Single value is stored)
• Native Lazy Loading: Active/Inactive
• Noscript Fallback: Active/Inactive

Preload

• Fetchpriority: Active/Inactive

CDN

• Supported Media Types: JPG | PNG | WEBP | GIF (Multiple values are stored)
• Background Images: Active/Inactive
• Dynamic Resizing: Active/Inactive
• Preferred CDN File Format: WebP | AVIF | None (Single value is stored)
• REST API: Active/Inactive

Settings

• Automatic Compression: Active/Inactive
• Remove Metadata from Images: Active/Inactive
• Optimize Original Images: Active/Inactive
• Automatic Resizing: Active/Inactive
• Set Image Dimensions: Active/Inactive
• Image Sizes: All | Custom (Single value is stored)
• Large Image Resizing – Resize Original Images: Active/Inactive
• Large Image Resizing – Disable Scaled Images: Active/Inactive
• PNG to JPEG Conversion: Active/Inactive
• Email Notification: Active/Inactive
• Next-Gen Formats: WebP | AVIF (Single value is stored)
• Gutenberg Support: Active/Inactive
• Gravity Forms: Active/Inactive
• WPBakery Page Builder: Active/Inactive
• Amazon S3: Active/Inactive
• NextGen Gallery: Active/Inactive
• Share Usage Data: Active/Inactive
• Preserve Settings: Active/Inactive

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 to trigger the refresh.

Share Usage Data

Sharing usage data 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 sharing usage data, toggle on Share Usage Data.

Preserve Settings

Preserve Settings keeps your configurations saved if you uninstall the plugin. It is enabled by default. Disable it if you want Smush to wipe all settings upon uninstallation.

Reset to Factory Settings

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

Plugin Information

The plugin information panel displays general information about the plugin, including the current version number, release date, and developer details.

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.

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, go to Smush > Lazy Load & Preload and enable it under the Lazy Load section.

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 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, enable the Automatic Compression setting to automatically web optimize your images on upload.

If you already have images in your Media Library when installing Smush, click the Optimize Images button on the Dashboard screen to optimize any existing images.

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 Preferred CDN File Format feature built into the Smush CDN
• Using the local Next-Gen Formats feature

• Check for any loopback issues.
• Review the Site Health page in your wp-admin to see if there are any critical issues related to media or HTTP requests.
• Enable debug mode and check the debug.log file in the wp-content directory for any errors while running the scan or optimizing images.
• Perform a plugin conflict test.
• Check if WP Cron is disabled; it should be enabled for Smush or scan to work correctly.
• Check the wp-config.php file in your site’s root directory and remove this line if it’s there: define( 'DISABLE_WP_CRON', true );
• Check that the wp-cron.php file actually exists and is accessible. It should be in the root directory of your website on your server. Ensure it has the correct file permissions; it should be 644 for Smush to be able to access it.
• If the cron issue persists, try to set up a server cron or use a 3rd party cron service.
• Low Server Resources
• Memory Limit: Increase PHP memory limit if it’s under 128M.
• You can do so by adding these in your wp-config.php file:
  define( 'WP_MAX_MEMORY_LIMIT', '512M');
define( 'WP_MEMORY_LIMIT', '512M');
• On some servers, the above defines may not work as expected. In such a case, you can try to increase it by adding this to your php.ini or .user.ini file: memory_limit = 512M
• If both of the above fail, you could do this via your hosting panel, or get support from your hosting provider.
• Process Timeout: Increase PHP max execution time limit if it is under 120.
• You can do so by adding this to your php.ini or .user.ini file: max_execution_time = 300
• If the above fails, you could do this via your hosting panel, or get support from your hosting provider.
• Missing Libraries
• Images may fail to smush if GD or Imagick PHP extensions are missing on your server. To verify, please check if you can edit an image on your site. If not, please ask your hosting provider to activate GD or Imagick PHP extension in order to resolve this.

Scan Issues

• Reduce Scan Slice Size: For stuck scans, you can add this to your wp-config.php file to see if reducing the slice size helps: define('WP_SMUSH_SCAN_SLICE_SIZE', 250 );
• Increase Scan Retry Limit: For failed scans, we limit the automated cron retries to 5 times. You can adjust the limit by adding this define to your wp-config.php file to see if it helps: define('WP_SMUSH_BACKGROUND_MAX_RETRIES', 20 );

Image Optimization Issues

• Disable Parallel Processing: Smush optimizes all the default WordPress image sizes for a media item in parallel, which makes the image optimization process much faster. But, it also requires more resources to do so. If you get stuck on optimizing images, try disabling Parallel Processing by adding this define in your wp-config.php file to see if it helps: define( 'WP_SMUSH_PARALLEL', false );
• Increase Smush Retry Limit: We limit the automated cron retries for Smush to 5 times per 1000 images. You can adjust the limit by adding this define to your wp-config.php file to see if it helps: define('WP_SMUSH_BULK_REVIVAL_LIMIT', 20 );
• Change compression level: If one or more images are not being properly optimized and are returning API errors, it may be due to the selected compression level. Thumbnail images generated by WordPress can usually be effectively compressed using the Basic compression level. However, images can occasionally not compress successfully in Basic compression level due to being already heavily optimized or too large for the method employed at this level. This can be especially true if you have also opted to optimize your original images. Try switching to Super or Ultra compression levels which utilize a lossy technique that is more aggressive and suitable for larger or original images.

• Use the Restore all images option to regenerate thumbnails. To make sure this works effectively, ensure that the Backup original images option is enabled.
• Consider using any authentic third-party WordPress plugins to regenerate your thumbnails.
• Disable lazy loading or switch to the native lazy loading feature. Please let us know if this resolves any underlying conflicts, as we want to address any issues that arise.
• If a CDN is currently enabled, try turning it off and let us know if this resolves any problems, so we can take steps to prevent similar issues in the future.

Note: Keep in mind that regenerating thumbnails may undo any previous optimizations.

Smush’s background processing feature requires Loopback Requests to work. Various factors can cause issues with loopback requests. If your site has such an issue, you’ll see the following error message on the Site Health screen.

Here is a list of the recommended solutions to fix this issue:

1. Edit Server Host File – If your domain is not hosted with WPMU DEV, then add the following line “127.0.0.1 yourdomain.com” to your server host file “/etc/hosts”. If it doesn’t work, check with your hosting provider or review the access logs to find the server’s private IP address and use that IP in place of 127.0.0.1. Note that “yourdomain.com” has to be replaced with your domain name with TLD.
2. Perform a Plugin Conflict Test – Certain plugins/themes can conflict with loopback requests causing this issue. Deactivate the themes/plugins on your site one by one and try to identify if deactivating any plugin/theme fixes the issue.
3. Temporarily Disable the Firewall – If you have a firewall enabled on your site, temporarily disable it to find out if it solves the issue. If so, then ask your hosting provider to add WPMU DEV IP addresses to the firewall’s allowlist.
4. HTTP Authentication – If your site is protected with basic HTTP authentication, then remove the authentication to see if it fixes the issue.
5. SSL Configuration issues – Poorly configured SSL certificates can also cause problems with loopback requests. Try to reinstall and reconfigure the SSL certificate as a fix.
6. DNS Update – If you have recently updated your nameservers or DNS records, wait for at least 48 hours for the issue to disappear.
7. Outdated Software – Verify all the Software on your system is up to date. Outdated software and libraries including PHP, cURL, or OpenSSL can also cause this issue. To verify that your system has the latest versions of the software, click on the Info tab under the Site Health screen of the Tools menu to reveal information about the software installed on your system.
8. Misconfigured DNS – Poorly configured or misconfigured DNS can raise cURL issues. Contact your hosting provider to troubleshoot any DNS and hosting-related issues.
9. Limited Resources – Limited Server Resources including the PHP memory limit and Maximum upload space can cause cURL request issues. Increase your server resources, as a fix.
10. Cloudflare Configuration – If your website is using Cloudflare make sure it is configured for WordPress by following this guide.
11. Contact Our Support – After trying out all the recommended solutions, if you still can’t troubleshoot the issue, 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.

When the Smush CDN can’t access a domain, or when some image URLs on the site can’t be fetched or optimized, one or more 429 rate limit errors may occur on the site. Usually, rate limits clear in 6 to 12 hours, but you may wish to investigate the cause of such issues to help prevent them from happening again right away.

The easiest way to do that is to check the response headers for any rate limited image.

Check Response Headers

Pop open your browser’s developer console and navigate to the Network tab, then reload a page of your site where you’ve noticed the issue. Locate the troublesome image in the left-hand pane and click on it (you can filter the list to show only image data by clicking on the Img filter button).

Under the Headers tab in the right-hand pane, scroll down until you find x-rate-limit-reason.

Images that are corrupted or not found should be replaced. Timeout errors could indicate that something is blocking the CDN from accessing the site.

However, if the image does not load from the CDN but loads correctly at its original URL, you may wish to contact support to have the rate limit cleared and the cause investigated more deeply.

Allow Smush CDN in Firewall

The Smush CDN operates from a cluster of IP addresses with no proxy, and to prevent man-in-the-middle attacks, those IPs are not publicly exposed. So if the Smush CDN is being blocked from accessing your site or domain, it is not possible to allowlist a series of IP addresses.

However, you can create a custom rule in your firewall settings to allow the CDN access. You would want your rule to contain the following directives:

• Request method: HEAD or GET
• Path contains /wp-content/uploads/
• ASN AS14061 DIGITALOCEAN-ASN

For example, if you are routing your domain through Cloudflare, you could create a custom rule like below:
(http.request.uri.path contains "/wp-content/uploads/" and ip.src.asnum eq 14061 and http.request.method eq "HEAD") or (http.request.uri.path contains "/wp-content/uploads/" and ip.src.asnum eq 14061 and http.request.method eq "GET")

In your Cloudflare account, go to Security > Security rules > Custom rules > New custom rule, and enter the directives as shown in the image below:

Next, select Skip as the Action, and enable all components including those under the More toggle. Finally, set the Order to First, and click the Deploy button to save the rule.