Step-by-step guide to install and use ShortPixel Adaptive Images (SPAI)

In this guide, you will see how you can install ShortPixel Adaptive Images (SPAI), an explanation of its settings and how to know if SPAI is working well, and if it isn't, how to solve it. Let's go!

1) Installing ShortPixel Adaptive Images

There are 3 ways you can install SPAI, and they are the same as with every other plugin.

Install SPAI using WordPress Plugin Search

First thing you need to do is go to your WordPress admin area and click on Plugins > Add New. Then, write on the search field "shortpixel adaptive images".

Now, click on "Install Now" on the ShortPixel Adaptive Images box. The button will change to "Activate". Click on it and that's it!

Install SPAI using the WordPress Admin Plugin Upload

You can also download an upload the plugin, if you don't feel like using the plugin search. First, go to the plugin page by clicking here and download the plugin.

Go to your WordPress admin area and go to Plugins > Add New > Upload Plugin
Click on "Choose File", look for the .zip that you just downloaded, select it, and upload it here by clicking on "Install Now". After activating it, that's it!

Manually Install a WordPress Plugin using FTP

The 3rd way, which is for experienced users, is to download and upload the plugin via FTP. First of all, download the plugin as we've seen before.

Now, extract the .zip file on your computer. Extracting the plugin .zip file will create a new folder with the same name. This is the folder that you need to manually upload to your website using a FTP client.

Open the FTP client on your computer and connect to your website using the login credentials provided by your web host. Once connected, you need to access the path 


Next, upload the folder you extracted from the .zip file to the above path on your web server.

After uploading the files, you need to visit the WordPress admin area and click on the "Plugins" link in the admin menu. You will see your plugin successfully installed on the plugins page.

And you need to click on the "Activate" link below the plugin.


2) Onboarding Wizard

If it's the first time you are using ShortPixel Adaptive Images, you will now be redirected to the Onboarding Wizard:

This 4-step wizard will help you configure SPAI properly so all your images are served from our CDN optimized.

If, for example, you were already using SPAI and updated to the new version, you can restart the wizard by going to Settings > ShortPixel AI and clicking on the "Setup Wizard" button located on the top right Help menu:

Please note that ShortPixel Adaptive Images does not require an API Key to start working. You only need to associate your website/domain to your account so that your ShortPixel credits will be used, and that will be automatically done by the Onboarding Wizard.

After you complete the Onboarding Wizard, be sure to clear the cache of your site: How to clear WordPress cache

3) Settings

ShortPixel is very easy to use, as it starts doing its magic right after activating and setting it up with the Onboarding Wizard; no need to click on any ON button or similar. However, SPAI also provides you with some settings to tune your image optimization. To access, just log in to your WordPress admin area and go to Settings > ShortPixel AI.

Remember to clear the cache of your site after changing your settings: How to clear WordPress cache


  • Compression Level: Check out this article to know more about it.
  • WebP Support: WebP images are the next generation of images, specially designed for the web. In short, WebP images are 26% smaller in size compared to PNGs and 25-34% smaller than comparable JPEG images. Here is more information about them. ShortPixel offers you the possibility to have WebP support with just a single click. We recommend you to activate this setting unless you know you will have some compatibility issues. You can check the browsers that support this image format here.
  • Remove EXIF: Just like SPIO does, to make the image a little bit smaller you can enable this option and remove all the information the image has, like author, location, camera, etc.


  • Fade-in effect: In order to work properly, SPAI lazy-loads the images. This means that they won't be loaded until they are needed, which is when they will be visible on the user's screen. In order to make the transition from invisible to visible smooth, SPAI fades-in the images, but if for some reason you experience problems with images with special effects, try disabling this option.
  • Smart crop: The plugin will identify cases when not all the image is displayed and crop it accordingly. This might not work for some backgrounds, but it won't harm them.
  • Replace method: This modifies how SPAI will replace the images with the optimized ones (remember that SPAI changes the URL of the image).
    • SRC: this is the recommended method. It makes sure the images remain only with the SRC attribute which resizes to the placeholder.
      • Generate <noscript> tag: If you are in a browser that do not allow/support JavaScript, then you should activate this in order to let SPAI work correctly. Please notice that this is not a "no-JavaScript" switch; this is a workaround, as SPAI works better if JavaScript is enabled.
    • BOTH (experimental): it does the same as SRC but it also keeps the SRCSET attribute while replacing images in it (but not resizing them).
    • SRCSET (experimental): it only replaces images in the SRCSET attribute.
  • API URL: you can make SPAI work with your own CDN, and this is the field to configure. Do not modify it unless you know what you are doing. For more information about this, check this article.
  • Lazy-load threshold: This sets how early before entering the visible area of the page (viewport) a lazy image is loaded. For example, the default of 500px means that an image is loaded when it's closer than 500px to the viewport. If unsure, don't change it.
  • Images hover handling: this applies to situations when you have a different image when hovering on an existing image. For example, there are sites which have grayed out logos of partners or customers (in testimonials) and when you hover, they become colored. Enable this option if this is your case.
  • Logged-in users: By default, ShortPixel AI serves and optimizes your images even if you are logged in. However, if you want to save some CDN traffic and credits, or you can simply disable this option and then SPAI will only work for logged-out users (your visitors).
  • Native lazy-loading: Learn more here.
  • Alter width and height: You should turn this on if you want the HTML attributes "height" and "width" to reflect the actual size of the image after it has been resized by the plugin. One of the reasons you might want to activate this is if you have some screen size issues with images that are handled by JavaScript after they are resized by ShortPixel. Please notice that this alters the attributes, it does not add them if they are missing.
  • Sizes from postmeta: SPAI needs to know each image size to work properly. To do this, it first checks the filename (thumbnails usually have the dimensions appended to it) and then, the physical image itself on disk. If SPAI cannot determine the size either way, it resorts to looking for the information on the "postmeta" database table.

    If the option is enabled, SPAI will do that database check when it needs to. If the option is disabled, this last check inside the database will not be done anymore and because of this, in some cases, when the image information isn't found in the other 2 places, SPAI will assume that it simply does not know the image size.

    This option is recommended to be disabled if you notice a high MySQL load that goes away if you deactivate SPAI. In case of doubt, you shouldn't change it.


  • Serve SVGs through CDN: You can make SPAI serve your SVGs from our CDN. They will remain unoptimized, though. ShortPixel does not optimize SVG files.
  • Lazy-load the backgrounds
    • Lazy-load the background images from inline STYLE blocks: if you have background images in inline style blocks on your HTML page, this option will lazy load them and therefore serve them as WebP (if it's enabled). For example:
      			body {
      				background-image: url("");
      				background-color: #cccccc;
    • Lazy-load and resize the background images in TAGS inline styles: if you have background images in the style attributes of your HTML tags, this option will lazy load them and therefore serve them as WebP (if it's enabled). For example:
      <div style="background-image:url('')">...</div>
  • Backgrounds maximum width: If the previous option is not selected, you can impose a maximum width to your background. Useful for those huge background that you don't want to lazy load.
  • Replace in CSS files: See this article.
  • Replace in the JS blocks: Some plugins or themes have galleries or other effects where images are served in JavaScript blocks. In this case, you'll have to activate this option.
  • Replace in JSON data: Check this if you have specific pieces of content that are delivered by Javascript in JSON-encoded packages. Some galleries will benefit from this, like Thrive Architect's. For more information, click here.
  • Integrate with Lity: If your theme uses the Lity lightbox, you should enable this.


  • Excluded selectors: here you can write the CSS selectors you want SPAI to exclude from optimization.
    • If you write them in "Don't lazy load", such selectors won't be lazy loaded, but they will still be optimized and resized. Please notice that any images not lazy loaded will not be delivered as WebP for technical reasons.
    • If you write them in "Don't resize", SPAI will optimize such images but not resize them.
    • If you write them in "Leave out completely", SPAI will completely ignore them, no optimization nor resizing.
  • Excluded URLs: if you want SPAI to ignore some of your images by URL, this is where you exclude them, using regular expressions (to exclude all GIFs or all PNGs, for example) or paths (to exclude a single image, for example). The plugin includes already a good explanation on how to use this field, make sure to check it out!

Be sure to read more about exclusions here: How to exclude images from optimization in the ShortPixel Adaptive Images plugin

4) Image Checker

After all the settings are in place, be sure to check out the new Image Checker tool: How to use the Image Checker tool.


Stop right here! Clear your cache before proceeding: How to clear WordPress cache

Now, the first question that comes to mind is: "Is SPAI working well on my website?" You can find out while reading this article!

We also updated our knowledge base with many articles that will help you out when something is not working as expected:

  • First of all, for the most common reasons of malfunctioning, check out this article
  • If you notice that no images are properly resized, this article helps you debug everything yourself, step-by-step.
  • If, in general, SPAI works correctly, but you still have some images that are not being served by our CDN, try activating one of the following options, located on Settings > ShortPixel AI > Areas:
  • Are you using GTmetrix or PageSpeed Insights? Do you get one or more image-related warning messages?
    • "Use explicit width and height on image elements": Read this
    • "Properly size images": Read this
  • Do your images appear as "data:image/svg" if you inspect the code? Then read this.
  • SPAI is not serving the WebP images correctly? Maybe it does!
  • Do you get a 500 error when installing the plugin? Make sure to read this.
Did this answer your question? Thanks for the feedback There was a problem submitting your feedback. Please try again later.

Still need help? Contact Us Contact Us