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

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.


  • 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 check this option and remove all the information an 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 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, and if you are using StackPath as CDN, check this article too.
  • 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.


  • 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: If you have background images in style blocks, this option will lazy load them and therefore serve them as WebP (if it's enabled). For example:
    <div style="background-image:url('')">...</div><br><br>
  • 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 files: 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.
  • Native lazy-loading: Native lazy-loading is the browser's capability to lazy load images, when certain tags are placed on the images. Therefore, activating this option will make SPAI use the browser's native lazy loading capabilities, instead of running some additional JavaScript for lazy loading images.


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


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 scaled, 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, maybe you should activate one of the following options:
  • Are you using GTmetrix? Do you get one or more image-related warning message?
    • "Specify a cache validator": Read this
    • "The following image(s) are missing width and/or height attributes": Read this
    • "Properly size images": Read this
    • "Minimize redirects": Read this
  • Do your images appear as "data:image/svg"? 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.

Still need help? Contact Us Contact Us