Google's PageSpeed webserver module for Nginx.

Configuring and monitoring the PageSpeed module in Nginx

This is a handy guide on how to properly configure the Google's PageSpeed webserver module on Nginx and how to monitor it and check if it's working.


Google’s PageSpeed is a webserver module which works by applying a series of filters designed to optimize not only the response of a webserver but also the assets being served. This is achieved by, among many other things, mimifying the JavaScript and CSS files, optimizing the HTML code and reducing the size of the assets like images and other media. All the optimization changes are internal, which means no extra code is needed from your part.

In total PageSpeed comes with 40 plus filters, each of these designed after one of Google’s best practices for web performance rules. PageSpeed also contains an “output filter” plus several content handlers. Furthermore, besides certain specific directives have to include in your main configuration file, most PageSpeed directives can be used in conjunction with a location rule in a server block in order to enable or disable them in certain parts of your website.

If you need help compiling PageSpeed with Nginx you can read this handy guide: how to compile Nginx with PageSpeed.

PageSpeed’s filters

Some of the most useful filters are

CSS optimization filters:

  • Combine CSS, combines multiple CSS sheets into one.
  • CSS cache extension
  • Flatten CSS Imports, replaces the @import rules with the contents of the imported files
  • Inline CSS, inserts the contents of small internal CSS files directly into the HTML documen.
  • Inline Google Fonts
  • Move CSS Above Scripts
  • Move CSS to Head
  • Prioritize critical CSS, replaces stulesheets wih inlined CSS rules.
  • Rewrite CSS, mimifies teh CSS

JavaScript optimization filters

  • Canonicalize JS libraries, replaces JS libraries with remote versions.
  • Combine JS, combines multiple JS files into on.
  • Defer JS, defers the loading of JS files until the page is loaded.
  • Inline JS, inserts external JS files into the HTML.

Images optimization filters

  • Extend cache for images
  • Lazyload images, loads images as needed
  • Inline images, includes image data into the webpage code
  • Conversion filter, filters to convert GIFs to PNG, JPEGs to progressive JPEGs, JPEG to WEBP, etc.
  • Recompression filters
  • Strip Image color profile
  • Strip Image Meta Data
  • Resize images, replaces any images larger than needed with smaller versions
  • Insert Image dimensions
  • Resize Images to Rendered Dimensions
  • Sprite Images, combines all background images from stylesheet rules into one big images.

HTML optimization filters

  • Add Heard, adds a <HEAD> tag if there’s none, this is required by other filters in order to work.
  • Collapse Whitespace, eliminates de whitespace.
  • Combine Heads, groups several heads elements into one.
  • Convert Meta Tags, adds matching present meta tags response head.
  • Elide Attributes: removes html tags attributes with values equal to default values.
  • Local Storage Cache, saves inlined resources into the browsers local cache.
  • Pedantic, forces HTML4 compliant.
  • Remove Comments, removes HTML comments
  • Remove Quotes, Deletes quotation marks from HTML attributes.
  • Trim URLs, replace absolute URLs with relative URLs.


Some of the filters like lazyload_images, inline_preview_images, and inline_images use beacons in order to collect information from visitors and then create certain profiles that will help rewriting the pages to be served more efficiently. The beacon is sent back to your sever through a POST request sent by a JavaScript script inserted by PageSpeed.

Monitoring PageSpeed

Simple monitoring

You can check if PageSpeed is working and if the filters you’ve selected are loading by inputting a special GET request string into your URL:

Once you load the webpage with that GET string, at the very end of your webpage’s HTML code PageSpeed will embed a report with all the enabled filters and their state.

Advanced monitoring

Advanced monitoring requires enabling certain rules to your PageSpeed configuration. In order to enable them just when you need them, we’ll include them in a separate file that will be included into the main PagesSpeed config file. Remember to comment the include when you don’t need to monitor your performance.

File: pagespeed_monitoring.conf

## PageSpeed admin pages configuration
pagespeed UsePerVhostStatistics on;
pagespeed StatisticsLoggingIntervalMs 60000;
pagespeed StatisticsLoggingMaxFileSizeKb 1024;
pagespeed MessageBufferSize 100000;
pagespeed StatisticsPath /monitor/ngx_pagespeed_statistics;
pagespeed GlobalStatisticsPath /monitor/ngx_pagespeed_global_statistics;
pagespeed MessagesPath /monitor/ngx_pagespeed_message;
pagespeed ConsolePath /monitor/pagespeed_console;
pagespeed AdminPath /monitor/pagespeed_admin;
pagespeed GlobalAdminPath /monitor/pagespeed_global_admin;

## Enable these if you want to see the admin console
pagespeed LogDir /var/log/pagespeed;
pagespeed Statistics on;
pagespeed StatisticsLogging on;

## Add auth basic rules or IP blocks here if you wan to secure
#  the URLs
location /monitor/ngx_pagespeed_statistics { }
location /monitor/ngx_pagespeed_global_statistics { }
location /monitor/ngx_pagespeed_message { }
location /monitor/pagespeed_console { }
location ~ ^/monitor/pagespeed_admin { }
location ~ ^/monitor/pagespeed_global_admin { }

If you include that file into your main PageSpeed configuration file you’ll be able to access the console through the following URL:

Configuring PageSpeed

In Nginx the configuration typically should go in your nginx.conf. So remember to include the following in your nginx.conf file.

include "pagespeed_main.conf";

Main configuration file

The main configuration file will setup all the necessary directives you need to run PageSpeed optimally.

File: pagespeed_main.conf

## PageSpeed Main Configuration File
pagespeed                                 on;
# Disable this if you don't want PageSpeed to add a header field
pagespeed XHeaderValue                   "Powered By ngx_pagespeed";

## Pagespeed monitoring
# Uncomment this line if you want to monitor PageSpeed: 
# include                                "pagespeed_monitoring.conf";

## PageSpeed configurations
pagespeed FetchWithGzip                  on;
pagespeed ProcessScriptVariables         on;

## PageSpeed filter settings
pagespeed RewriteLevel                   CoreFilters;
pagespeed BlockingRewriteKey             "fullyoptimized";

pagespeed DisableRewriteOnNoTransform    off;
pagespeed SupportNoScriptEnabled         false;
pagespeed RespectVary                    off;
pagespeed ModifyCachingHeaders           on;
pagespeed ListOutstandingUrlsOnError     on;

## Cache variables
pagespeed MaxCacheableContentLength      -1;
pagespeed FileCachePath                  "/var/cache/ngx_pagespeed_cache";
pagespeed FileCacheSizeKb                102400;
pagespeed FileCacheCleanIntervalMs       3600000;
pagespeed FileCacheInodeLimit            500000;
pagespeed LRUCacheKbPerProcess           1024;
pagespeed LRUCacheByteLimit              16384;
## Speed up PageSpeed by storing it in memcached
#  Disable this if you don't use memcached
pagespeed MemcachedThreads               1;
pagespeed MemcachedServers               "localhost:11211";

## PageSpeed Cache Purge
pagespeed EnableCachePurge               on;
pagespeed PurgeMethod                    PURGE;
pagespeed DownstreamCacheRewrittenPercentageThreshold 95;

## Pagespeed rules
# Remember to comment this line if you want to include the rules in a server block. 
include                                  "pagespeed_rules.conf";

Note: create the cache directory if your Nginx daemon can’t create directories in /var/cache/

sudo mkdir /var/cache/ngx_pagespeed_cache
sudo chmod 700 /var/cache/ngx_pagespeed_cache

# Replace www-data for your Nginx user if you configured nginx with
# another user. 
sudo chown www-data:www-data /var/cache/ngx_pagespeed_cache

PageSpeed’s rules file

Important: you can either include this file into your main nginx.conf to enable it everywhere across your server OR you can include it in the server{} block of the sites where you want these rules enabled. You’ll need to include this file in any of these two locations.

Note: you can also create multiple rule files for your different sites in the same server.


## PageSpeed configurations
pagespeed MaxCacheableContentLength -1;
pagespeed FetchHttps enable,allow_self_signed;

## Core filters
## Images
# Image optimizaion
pagespeed EnableFilters jpeg_subsampling;
pagespeed EnableFilters convert_png_to_jpeg;
pagespeed EnableFilters resize_images;
pagespeed EnableFilters convert_jpeg_to_webp;
pagespeed NoTransformOptimizedImages on;
pagespeed EnableFilters convert_to_webp_lossless;
pagespeed EnableFilters recompress_jpeg;
pagespeed EnableFilters recompress_png;
pagespeed EnableFilters recompress_webp;
pagespeed EnableFilters convert_gif_to_png;
pagespeed EnableFilters convert_jpeg_to_progressive;
pagespeed EnableFilters resize_mobile_images;
# other image improvements
pagespeed EnableFilters lazyload_images;
pagespeed EnableFilters dedup_inlined_images;
pagespeed EnableFilters inline_preview_images;
pagespeed EnableFilters inline_images;
pagespeed EnableFilters strip_image_color_profile;
pagespeed EnableFilters strip_image_meta_data;
pagespeed EnableFilters resize_rendered_image_dimensions;
pagespeed EnableFilters insert_image_dimensions;
pagespeed EnableFilters sprite_images;

## Text / HTML
pagespeed EnableFilters elide_attributes;
pagespeed EnableFilters pedantic;
pagespeed EnableFilters remove_comments;
pagespeed EnableFilters remove_quotes;
pagespeed EnableFilters trim_urls;
pagespeed EnableFilters combine_heads;
pagespeed EnableFilters collapse_whitespace;
pagespeed EnableFilters convert_meta_tags;

## JavaScript
pagespeed EnableFilters combine_javascript;
pagespeed EnableFilters canonicalize_javascript_libraries;
pagespeed EnableFilters inline_javascript;

## CSS
pagespeed EnableFilters outline_css;
pagespeed EnableFilters combine_css;
pagespeed EnableFilters inline_import_to_link;
pagespeed EnableFilters inline_css;
pagespeed EnableFilters inline_google_font_css;
pagespeed EnableFilters move_css_above_scripts;
pagespeed EnableFilters move_css_to_head;
pagespeed EnableFilters prioritize_critical_css;
pagespeed EnableFilters rewrite_css;
pagespeed EnableFilters fallback_rewrite_css_urls;
pagespeed EnableFilters rewrite_style_attributes_with_url;

## Cache extensions
pagespeed EnableFilters extend_cache_pdfs;
pagespeed EnableFilters extend_cache;
pagespeed EnableFilters local_storage_cache;

## Misc
pagespeed EnableFilters insert_dns_prefetch;
# Useful for tracking load times
pagespeed EnableFilters add_instrumentation;

## Configuring the beacons
location ~ "\.pagespeed\.([a-z]\.)?[a-z]{2}\.[^.]{10}\.[^.]+" {
  add_header "" "";
location ~ "^/pagespeed_static/" { }
location ~ "^/ngx_pagespeed_beacon$ps_dollar" { }

# Disable this if you aren't using WordPress
#pagespeed Disallow "*/wp-admin/*";
#pagespeed Disallow "*/wp-login.php*";

Remember to read our guide on how to compile Nginx with PageSpeed.

Leave a Reply