LiteSpeed Cache Configuration

Navigate to LiteSpeed Cache > Configuration.



  • Enable LiteSpeed Cache: Must be set to YES to use LiteSpeed Cache.
  • Default Public Cache TTL: Default timeout for publicly cached pages. Recommended value is 86400.
  • Default Private Cache TTL: Default timeout for private cache ESI blocks. Suggested value is 1800. Must be less than 7200.
  • Home Page TTL: Default timeout for the home page. If you have random displayed items, you can have shorter TTL to make it refresh more often.
  • 404 Pages TTL: Default timeout for all 404 (Not found) pages. 0 will disable caching for 404 pages.
  • Separate Mobile View: Enable this if you have a separate mobile theme.
  • Separate Cache Copy per Customer Group: Enable this option if there is different pricing based on customer groups.
  • Flush Product and Categories When Order Placed: Determines how changes in product quantity and stock status affect product pages and their associated category pages.
  • Enable Guest Mode: This will speed up the first page view for new visitors by serving the default view. Robots will get an instant response without hitting the backend. If you have different views based on GeoIP, select First Page Only to make sure the second page will have the correct view.

User-Defined Cache Rules


You only need to set a page as NOT-CACHEABLE if it is being cached by default.

  • Do-Not-Cache GET Parameters: Comma-separated list of GET variables that prevents caching URLs within Cacheable Routes.
  • URL Blacklist: List of relative URLs contained in Cacheable Routes to be excluded from caching. They start with / and don’t include the domain name. Partial matches can be performed by adding an * to the end of a URL. Enter one relative URL per line.

Developer Testing


  • Enable Cache Only for Listed IPs: Limit LiteSpeed Cache to specified IPs. (Space or comma separated.) Allows cache testing on a live site. If empty, cache will be served to everyone.
  • Enable Debug Log: Prints additional information to lscache.log. Turn off for production use.
  • Log Only for Listed IPs: Only log activities from specified IPs. (Space or comma separated.) If empty, all activities will be logged. Only effective when debug log is enabled.
  • Debug Level: Specifies log level ranging from 1 to 10. The higher the value, the more detailed the output.

Customization for PrestaShop 1.6

The following widgets and features require further customization before they can be used with LSCPS:

  • Viewed Products Block
  • Compare Products Feature
  • Blockcart Template

Viewed Products Block

The use of the Viewed Products Block module is not recommended as it is not cache friendly. Disable it in the Modules List area.


Compare Product Feature

If you are using the Compare Product feature, you will need to define an ESI block around it in order for it to work properly with LSCPS.

Open the appropriate template file in an editor. The default template is located at themes/default-bootstrap/product-compare.tpl but if you have a custom theme, it will be under that theme's folder.

Locate the following text: {count($compared_products)}.

Anywhere this text appears, surround it with LiteSpeed ESI hooks like so:

{hook h="litespeedEsiBegin" m="lsc_compareproduct" field="comparedcount"}{count($compared_products)}{hook h="litespeedEsiEnd"}


Be careful not to add extra spaces or line breaks in between!

This is the default template after the substitutions have been made. Your template should look similar:

{if $comparator_max_item}
    <form method="post" action="{$link->getPageLink('products-comparison')|escape:'html':'UTF-8'}" class="compare-form">
        <button type="submit" class="btn btn-default button button-medium bt_compare bt_compare{if isset($paginationId)}_{$paginationId}{/if}" disabled="disabled">
<span>{l s='Compare'} (<strong class="total-compare-val">{hook h="litespeedEsiBegin" m="lsc_compareproduct" field="comparedcount"}{count($compared_products)}{hook h="litespeedEsiEnd"}</strong>)<i class="icon-chevron-right right"></i></span>
        <input type="hidden" name="compare_product_count" class="compare_product_count"
               value="{hook h="litespeedEsiBegin" m="lsc_compareproduct" field="comparedcount"}{count($compared_products)}{hook h="litespeedEsiEnd"}" />
        <input type="hidden" name="compare_product_list" class="compare_product_list" value="" />
    {if !isset($paginationId) || $paginationId == ''}
        {addJsDefL name=min_item}{l s='Please select at least one product' js=1}{/addJsDefL}
        {addJsDefL name=max_item}{l s='You cannot add more than %d product(s) to the product comparison' sprintf=$comparator_max_item js=1}{/addJsDefL}
        {addJsDef comparator_max_item=$comparator_max_item}
        {addJsDef comparedProductsIds=$compared_products}
{addJsDef comparedProductsIds=$compared_products}
You'll notice that {count($compared_products)} appeared twice, and was surrounded with the ESI hooks both times.

Blockcart Template

A pop-up overlay appears when an item is added to the cart, if the request hits the backend. If the request is served from cache, the overlay does not appear, though the cart is updated properly. This occurs in the default-bootstrap theme and others.


This is caused by the smarty template active_overlay counter. When the content is served from an ESI block as a separate request, the counter value becomes 2. So if you want this overlay to always show, you need to modify your theme's smarty template.

Modify your_active_theme/modules/blockcart/blockcart.tpl

Locate the following lines:

{if !$PS_CATALOG_MODE && $active_overlay == 1}
<div id="layer_cart">

Change the first line to this:

{if !$PS_CATALOG_MODE && $active_overlay}

Now the pop-up overlay will always appear. Please remember if you ever update your theme, you will need to apply these changes again.

Customization for PrestaShop 1.7

PrestaShop v1.7 introduces {widget} and {widget_block} elements that can be used in Smarty templates directly.

To ensure a hole is punched for a widget, you must define it as an ESI block. Currently, this can be automated in widgets, but not in widget blocks. You will have to manually place LSCache hooks to mark the beginning and the end of each ESI block in the template. LSCache relies on these hooks to trigger the ESI injection.


As of this writing, the cart (ps_shoppingcart) and login (ps_customersignin) blocks are the only blocks we know of that are impacted by the issue.

Both cart and login blocks already have hooks defined in the default “classic” template so there is no need to change template files for those particular blocks in that particular template. However, if ps_shoppingcart and ps_customersignin are not triggered through hooks or through {widget}, but through {widget_block}, you will have to manually update the template file.

Widget Blocks as ESI Blocks

If there’s any HTML code, it will need to be put aside into a template file. So this:

{widget_block name=”module_name”}
Smarty / html
becomes this:
{hook h="litespeedEsiBegin" m="module_name" field="widget_block" tpl="template_path.tpl"}
{widget_block name=”module_name”}
Smarty / html
{hook h="litespeedEsiEnd"}

The contents of <template_path>.tpl should exactly match what is written in the Smarty / html section.

This allows us to use ESI to punch a hole for this widget and regenerate the content later.

Example: Warehouse Theme

Let’s take the “warehouse” template as an example, and say header.tpl located at themes/warehouse/templates/_partials/header.tpl uses variant 1 in header.tpl:

{if $iqitTheme.h_layout == 1}
  {include file='_partials/_variants/header-1.tpl'}
As the above code indicated, the actual header template is {include file='_partials/_variants/header-1.tpl'}

You will need to modify _partials/_variants/header-1.tpl. Make sure you backup your file before doing any changes.

vi _partials/_variants/header-1.tpl
For ps_shoppingcart as widget_block, replace the following:
{widget_block name="ps_shoppingcart"}
    {include 'module:ps_shoppingcart/ps_shoppingcart-default.tpl'}
{hook h="litespeedEsiBegin" m="ps_shoppingcart" field="widget_block" tpl="module:ps_shoppingcart/ps_shoppingcart-default.tpl"} 
    {widget_block name="ps_shoppingcart"}
    {include 'module:ps_shoppingcart/ps_shoppingcart-default.tpl'}
    {hook h="litespeedEsiEnd"}
For ps_customersignin as widget_block, replace the following:
 {widget_block name="ps_customersignin"}
 {include 'module:ps_customersignin/ps_customersignin-btn.tpl'}
 {hook h="litespeedEsiBegin" m="ps_customersignin" field="widget_block" tpl="module:ps_customersignin/ps_customersignin-btn.tpl"} 
 {widget_block name="ps_customersignin"}
 {include 'module:ps_customersignin/ps_customersignin-btn.tpl'}
 {hook h="litespeedEsiEnd"}

Templates With Multiple Variants

Sometimes header.tpl may use multiple variants, like so:

  {if $iqitTheme.h_layout == 1}
      {include file='_partials/_variants/header-1.tpl'}
  {elseif $iqitTheme.h_layout == 2}
      {include file='_partials/_variants/header-2.tpl'}
  {elseif $iqitTheme.h_layout == 3}
      {include file='_partials/_variants/header-3.tpl'}
  {elseif $iqitTheme.h_layout == 4}
      {include file='_partials/_variants/header-4.tpl'}
  {elseif $iqitTheme.h_layout == 5}
      {include file='_partials/_variants/header-5.tpl'}
  {elseif $iqitTheme.h_layout == 6}
      {include file='_partials/_variants/header-6.tpl'}
  {elseif $iqitTheme.h_layout == 7}
      {include file='_partials/_variants/header-7.tpl'}

In this case, you will need to back up all seven header files, and make changes to these templates from header-1.tpl to header-7.tpl, the same way as shown above.

The PrestaShop Module Prestashop European Union Cookie Law can work with LSCache, but you will need to adjust a few settings in the LSCache Module.

Navigate to the Customization tab of the LiteSpeed Cache screen. Click Add New ESI Block at the top of the page.


Adjust the following settings:

  • Module = uecookie (select from dropdown)
  • Is Private = Yes
  • TTL = 1800 seconds
  • Cache Tag = uecookie
  • Hooked Methods = hookFooter if the cookie notice displays in the footer, and hookHeader if it displays in the header.
  • As Variable = Yes
  • Ignore if Empty = No
  • Only Cache When Empty = Yes

Testing LSCPS

To determine whether a page is being served from LSCPS, do the following:

  1. Navigate to your site, and open your browser's developer tools.
  2. Click on the Network tab in the inspector.
  3. Refresh the page.
  4. In another tab, navigate to the cache manager and purge your cache.
  5. Go back to the previous tab, reload the page and click the first resource listed in the inspector. This should be an HTML file, and might look like or /.
  6. You should see X-LiteSpeed-Cache: miss and something like X-LiteSpeed-Cache-Control:public,max-age=1800 and X-LiteSpeed-Tag:F,B.1. These mean LSCache is active and the current page will be cached for the next visitor.
  7. If you reload page a second time, you should see X-LiteSpeed-Cache: hit to indicate the page is being served by the cache and LSCPS is configured correctly.


If your first refresh after purging returns X-LiteSpeed-Cache: hit in the response header, this may be because someone visited the page after you purged but before you refreshed it yourself.

Cache Crawler Script

The crawler travels through your site, refreshing pages that have expired in the cache. This makes it less likely that your visitors will encounter un-cached pages.

Before You Crawl

The crawler must be enabled at the server level, or you will see the warning message Server crawler engine not enabled. Please check..... If you are using a shared hosting server, please contact your hosting provider, or see our instructions.

You will need to prepare your site's sitemap, e.g. You can use Google, SiteMap, or do it yourself. It doesn't matter how you generate a sitemap, just as long as it is an XML sitemap.

Google Sitemap Module

For v1.6, Google Sitemap Module is installed by default.

For v1.7+, Google Sitemap Module needs to be installed from source first. Download gsitemap; then change the file name to

Click the Configure button, you will see e.g. xxx/1_index_sitemap.xml(This is your main SITE-MAP-URL, ).


SiteMap Online Generator

One of the popular sitemap generators is After the crawl is finished. Click DOWNLOAD YOUR XML SITEMAP FILE and put it where the crawler script can access it.


How to Use the LSCache Crawler Script

Download from here

Change the permissions so that the file is executable: chmod +x

To crawl when desktop & mobile share the same theme: bash SITE-MAP-URL

TO crawl when desktop & mobile have different themes: bash SITE-MAP-URL -m

By default, in the PrestaShop cache plugin, Mobile View is DISABLED. To enable mobile view, navigate to PrestaShop Admin > LiteSpeed Cache > Configuration and set Separate Mobile View to Yes


Crawler Script Options

  • -h, --help: Show this message and exit.
  • -m, --with-mobile: Crawl mobile view in addition to default view.
  • -c, --with-cookie: Crawl with site's cookies.
  • -b, --black-list: Page will be added to blacklist if HTML status error and no cache. Next run will bypass page.
  • -g, --general-ua: Use general user-agent instead of lscache_runner for desktop view.
  • -i, --interval: Change request interval. -i 0.2 changes from default 0.1 second to 0.2 seconds.
  • -v, --verbose: Show complete response header under /tmp/crawler.log.
  • -d, --debug-url: Test one URL directly. as in sh -v -d
  • -qs,--crawl-qs: Crawl sitemap, including URLS with query strings.
  • -r, --report: Display total count of crawl result.

Example commands

  • To get help: bash -h
  • To change default interval request from 0.1s to custom NUM value: bash SITE-MAP-URL -i NUM
  • To crawl with cookie set: bash -c SITE-MAP-URL
  • To store log in /tmp/crawler.log: bash -v SITE-MAP-URL
  • To debug one URL and output on screen: bash -d SITE-URL
  • To display total count of crawl result: bash -r SITE-MAP-URL


Using multiple parameters at the same time is allowed

Crawl Interval

How often do you want to re-initiate the crawling process? This depends on how long it takes to crawl your site and what you have set for Public Cache TTL. Default TTL is one day (24 hours). You might consider running the script by cronjob every 12 hours.
E.g. This will run twice a day, at 3:30/15:30: 30 3/15 * * * path_to_script/ SITE-MAP-URL -m -i 0.2


You can use an online crontab tool help you to verify time settings.

Verify the Crawler is Working

Use the browser developer tool, to look for the X-LiteSpeed-Cache: hit header on the first page view for both desktop and Mobile. If the page has been crawled, it will be a hit.

Desktop view


Mobile view


Translating the LSCache Module

LSCPS is written in United States English, and so we rely our our international users to help us translate the plugin for worldwide use. If you are fluent in a language other than English (US), and you have a few minutes to contribute to our plugin, we would appreciate it! Even if you don't want to share your localization efforts with the larger community, you can use these instructions to create a personalized translation for your own use.

Is Your Language Needed?

If we have a translation available in your language, it will come packaged with LSCPS. If you are still seeing the plugin interface in English, or, if the translation into your language is incomplete or incorrect in some way, we can definitely use your expertise.

How to Create a Translation

From the PrestaShop Admin, navigate to International > Translations.


For Type of translation, select Installed modules translations. A Select your module box will appear. Click on that and look for LiteSpeed Cache. You can type it in the search box, if you have a lot of modules to scroll through.

Choose your language from the Select your language drop-down box. You can only do a translation for languages that you have already installed in PrestaShop. In our example, we have English and Spanish installed, and we are selecting Español (Spanish).

Click the Modify button.


Begin translating! Once a section has been completed and saved, the pink boxes turn pale gray, and the EXPRESSIONS count is decreased accordingly. In our example, we've translated and saved the LITESPEEDCACHE section, but we've only just started working on the ADMINLITESPEEDCACHECONFIGCONTROLLER section.

Enter the translations for as many expressions as you know, and then press the Save button.

Now What?

Your string translations are stored in modules/litespeedcache/translations/<language>.php, where "" is the two-character code (for example, es.php for Spanish). If you are satisfied with your translation and you'd like to share it with the PrestaShop community, it's as simple as sharing the PHP file with LiteSpeed. Get in touch with us via email or slack, and let us know you have a new language to share.

Thank you for helping us make LSCPS accessible for a global audience!

Last update: August 11, 2020