• A+

To install our dependencies, run:

RedHat, CentOS, or Fedora
sudo yum install gcc-c++ pcre-devel zlib-devel make unzip
Ubuntu or Debian
sudo apt-get install build-essential zlib1g-dev libpcre3 libpcre3-dev unzip
Then download ngx_pagespeed:

unzip release-${NPS_VERSION}
cd ngx_pagespeed-release-${NPS_VERSION}-beta/
tar -xzvf ${NPS_VERSION}.tar.gz # extracts to psol/
Download and build nginx with support for pagespeed:

# check for the latest version
tar -xvzf nginx-${NGINX_VERSION}.tar.gz
cd nginx-${NGINX_VERSION}/
./configure --add-module=$HOME/ngx_pagespeed-release-${NPS_VERSION}-beta
sudo make install
If you are running a 32-bit userland with a 64-bit kernel, you will have build a 32 bit version of pagespeed instead of the default 64 bit version. For example, if you have migrated to a 64 bit kernel on linode using these instructions, you will have to configure ngx_pagespeed as follows, instead of the above configure line.

setarch i686 ./configure --add-module=$HOME/ngx_pagespeed-release-${NPS_VERSION}-beta
If this doesn't work for you, please let us know. You can post on our discussion group or file a bug.

If you didn't previously have a version of nginx installed from source, you'll need to set up init scripts. See

PageSpeed contains an "output filter" plus several content handlers.

Note: The location of the configuration file is dependent both on the Linux distribution on which PageSpeed is installed and on whether you're using PageSpeed with Apache or Nginx.

In Apache the configuration file is pagespeed.conf and will be in either:

Debian/Ubuntu: /etc/apache2/mods-available/
CentOS/Fedora: /etc/httpd/conf.d/
In Nginx the configuration typically should go in your nginx.conf which for source installs defaults to being in:
In Apache PageSpeed is enabled automatically when you install the module while in Nginx you need to add several lines to your nginx.conf. In every server block where PageSpeed is enabled add:

pagespeed on;

# Needs to exist and be writable by nginx. Use tmpfs for best performance.
pagespeed FileCachePath /var/ngx_pagespeed_cache;

# Ensure requests for pagespeed optimized resources go to the pagespeed handler
# and no extraneous headers get set.
location ~ "\.pagespeed\.([a-z]\.)?[a-z]{2}\.[^.]{10}\.[^.]+" {
add_header "" "";
location ~ "^/pagespeed_static/" { }
location ~ "^/ngx_pagespeed_beacon$" { }
See the Admin Page documentation for instructions on how to configure handlers to provide visibility and control into PageSpeed's operation.
Apache-Specific Configuration

Setting up the Output Filter

The output filter is used to parse, optimize, and re-serialize HTML content that is generated elsewhere in the Apache server.

# Direct Apache to send all HTML output to the mod_pagespeed output handler.
AddOutputFilterByType MOD_PAGESPEED_OUTPUT_FILTER text/html
Note: mod_pagespeed automatically enables mod_deflate for compression.

Turning the module on and off

To turn mod_pagespeed ON, insert as the top line of pagespeed.conf:

ModPagespeed on
There are two ways to disable mod_pagespeed. To disable HTML rewriting but continue to serve .pagespeed. resources and parse query options (for instance for ?ModPagespeed=on) put this line in your configuration:

ModPagespeed off
To completely disable mod_pagespeed (.pagespeed. resources will result in 404s) use the following line:

Note: New feature as of

ModPagespeed unplugged
The on and off values can be used in .htaccess files, scopes, query parameters, and headers. The unplugged value can only be used in the top-level Apache configuration and in virtual hosts. Note that ModPagespeed on in a virtual host can override a top-level unplugged directive.

Support for Apache 2.4.x

mod_pagespeed is compatible with Apache 2.2.x and Apache 2.4.x series, versions 2.4.2 and newer. Please note that Apache 2.4.1 has a bug that may cause stability problems in combination with mod_pagespeed, so use with 2.4.1 is strongly discouraged.

As Apache 2.4 is not API compatible with 2.2, support for it is provided via a separate module binary, instead of the usual The configuration provided in our binary packages will normally load the right module version automatically. However, if you upgrade the CentOS packages from an earlier version, the needed configuration change may not get applied on top of a user-customized pagespeed.conf, so you may need to adjust the LoadModule line manually.

Source builds with mod_pagespeed-provided Apache headers will build both 2.2.x and 2.4.x binaries as well, and you will need to add a LoadModule line matching the server version in use, or use a pattern similar to:

LoadModule version_module /usr/lib/apache2/modules/

LoadModule pagespeed_module /usr/lib/apache2/modules/

= 2.4.2>
LoadModule pagespeed_module /usr/lib/apache2/modules/

to auto-detect. Builds against system Apache headers will only be compatible with that version family, and will always produce a single module named
Nginx-Specific Configuration

Turning the module on and off

To turn ngx_pagespeed ON, put anywhere in your http or server block:

pagespeed on;
To turn ngx_pagespeed OFF, use off:

pagespeed off;
This is equivalent to the "unplugged" setting for mod_pagespeed, and entirely disables ngx_pagespeed.
Respecting Vary Headers

In order to maximize the number of resources that PageSpeed can rewrite, by default the module does not respect Vary: User-Agent and other Vary headers on resource files, such as JavaScript and css files. By disregarding the Vary headers, PageSpeed is able to keep the size of the cache down. PageSpeed will always respect Vary: Accept-Encoding, regardless of this setting. PageSpeed will also always respect Vary headers on HTML files, regardless of this setting.

If a site has resources that legitimately vary on User-Agent, or on some other attribute, then in order to preserve that behavior, you must add

ModPagespeedRespectVary on
pagespeed RespectVary on;
to your configuration file.

Please note that turning on this option will disable optimization of any resources with Vary headers, apart from Vary: Accept-Encoding.

Honoring no-transform Cache-Control Headers

Note: New feature as of

By default, PageSpeed does not rewrite resources that have Cache-Control: no-transform set in the Response Header. This is true for all types of resources, such as JavaScript, images, CSS etc. By respecting Cache-Control: no-transform headers, PageSpeed cannot optimize resources that could otherwise be rewritten.

To optimize resources irrespective of Cache-Control: no-transform headers, you must add

ModPagespeedDisableRewriteOnNoTransform off
pagespeed DisableRewriteOnNoTransform off;
to your configuration file.

Please note that PageSpeed will always respect Cache-Control: no-transform headers on HTML files irrespective of the setting. And also, PageSpeed will always retain the Cache-Control: no-transform headers on the resource irrespective of the setting so that the downstream cache control mechanisms do not get affected.

Lower-casing HTML element and attribute names

HTML is case-insensitive, whereas XML and XHTML are not. Web performance Best Practices suggest using lowercase keywords, and PageSpeed can safely make that transformation in HTML documents.

In general, PageSpeed knows whether a document is HTML or not via Content-Type tags in HTTP headers, and DOCTYPE. However, many web sites have Content-Type: text/html for resources that are actually XML documents.

If PageSpeed lowercases keywords in XML pages, it can break the consumers of such pages, such as Flash. To be conservative and avoid breaking such pages, PageSpeed does not lowercase HTML element and attribute names by default. However, you can sometimes achieve a modest improvement in the size of compressed HTML by enabling this feature with:

ModPagespeedLowercaseHtmlNames on
pagespeed LowercaseHtmlNames on;
These directives can be used in location-specific configuration sections.


This switch is only risky in the presence of XML files that are incorrectly served with Content-type: text/html. Lower-casing XML element and attribute may affect whatever software is reading the XML.

Preserving HTML caching headers

By default, PageSpeed serves all HTML with Cache-Control: no-cache, max-age=0 because the transformations made to the page may not be cacheable for extended periods of time.

If you want to force PageSpeed to leave the original HTML caching headers you can add:

ModPagespeedModifyCachingHeaders off
pagespeed ModifyCachingHeaders off;
Note: We do not suggest you turn this option off. It breaks PageSpeed's caching assumptions and can lead to unoptimized HTML being served from a proxy caches set up in front of the server. If you do turn it off, we suggest that you do not set long caching headers to HTML or users may receive stale or unoptimized content.

Specifying the value for the PageSpeed header

By default, PageSpeed adds an header, X-Mod-Pagespeed in Apache, X-Page-Speed in Nginx, with the version of PageSpeed being used. The format of this header is:

For example:
We update these following this schedule:

Major Version
Incremented when we make very large changes.
Minor Version
Incremented for each release since the last major version
Branch Number
Incremented for every release. Always increasing.
Point Number
Incremented each time we build a new release candidate or patch release, resets on each minor release.
Commit Number
Incremented each time we accept a commit to the PSOL trunk. Always increasing.
All servers running a given release will have the same value for this header by default. If you would like to change the value reported, you can use the XHeaderValue directive to specify what to use instead:

ModPagespeedXHeaderValue "Powered By mod_pagespeed"
pagespeed XHeaderValue "Powered By ngx_pagespeed";
Note: You cannot suppress the injection of this header. This is because it is used to prevent infinite loops and unnecessary rewrites when PageSpeed fetches resources from an origin that also uses PageSpeed.

Location-Specific Configuration

With an .htaccess file (Apache), scope (Apache), or location block (Nginx) you can control most of the PageSpeed directives. Note, however, that the file-matching is only relevant to the HTML file, and not to any of the resources referenced from the HTML file. To restrict resources by directory, you must use the PageSpeed Allow and Disallow directives, using full paths or wildcards in those directives.

Warning: Resources and the HTML files that reference them must have the same options. If they differ you may see poor performance and inconsistent application of options.

In Apache, the advantage of .htaccess is that it can be used in environments where the site administrator does not have access to the server configuration. However, there is a significant per-request overhead from processing .htaccess files. See The Apache HTTP Server Documentation:

Note: You should avoid using .htaccess files completely if you have access to the httpd main server config file. Using .htaccess files slows down your Apache server. Any directive that you can include in a .htaccess file is better set in a block, as it will have the same effect with better performance.

Virtual hosts are generally a better way of configuring multiple sites on the same server.

Using PageSpeed With Virtual Hosts

Note: New feature as of

By default PageSpeed installs itself for the entire server including all VirtualHosts (Apache) or server blocks (Nginx). If you want the exact same PageSpeed configuration for all VirtualHosts, you can just use the default configuration layout. You can, however, use different settings for some of the virtual hosts if you so chose.

In each virtual host, PageSpeed configures itself as follows:

If there are no PageSpeed-specific configuration options, then the global configuration is used.
If there are PageSpeed-specific options in the virtual host:
In Nginx, or in Apache when InheritVHostConfig is on, the global PageSpeed configuration will be inherited into the virtual host, which can override it as needed.
In Apache when InheritVHostConfig is off the virtual host starts off with an entirely clean PageSpeed configuration. This means if you turn PageSpeed on in that host, you will also need to repeat FileCachePath and any other settings.
If you are using version or newer, a convenient approach is to put the common settings in the global configuration and put only site-specific configuration in each host's section. In Apache this requires setting ModPagespeedInheritVHostConfig on in the global configuration.
ModPagespeed On
ModPagespeedInheritVHostConfig on
ModPagespeedFileCachePath "/var/cache/mod_pagespeed/"
ModPagespeedEnableFilters combine_css,combine_javascript
# Direct Apache to send all HTML output to the mod_pagespeed
# output handler.
AddOutputFilterByType MOD_PAGESPEED_OUTPUT_FILTER text/html

NameVirtualHost *:80

DocumentRoot /www/example1
ModPagespeedMapRewriteDomain *

DocumentRoot /www/example2
ModPagespeedMapRewriteDomain *
# Don't want combine_css here
ModPagespeedDisableFilters combine_css

DocumentRoot /www/example3
# mod_pagespeed off for this virtual host
ModPagespeed Off

http {
pagespeed On;
pagespeed FileCachePath "/var/cache/ngx_pagespeed/";
pagespeed EnableFilters combine_css,combine_javascript;

server {
listen 80;
root /www/example1;
pagespeed MapRewriteDomain *;

server {
listen 80;
root /www/example2;
pagespeed MapRewriteDomain *;
# Don't want combine_css here
pagespeed DisableFilters combine_css;

server {
listen 80;
root /www/example3;

# mod_pagespeed off for this virtual host
pagespeed off;
If you're using a version older than, you will need to repeat the common settings in each virtual host. Putting the common settings in a separate file and then using the Include directive is a good way of making such installs manageable. Note that you should not copy over AddOutputFilterByType MOD_PAGESPEED_OUTPUT_FILTER text/html to the virtual hosts if that is in the global scope as copying it over would end up adding it multiple times.

Preserve URL Relativity

Note: New feature as of

Previous versions of PageSpeed would rewrite relative URLs into absolute URLs. This wastes bytes and can cause problems for sites that sit behind HTTPS terminators.

With PreserveUrlRelativity on, PageSpeed will keep URLs the way they were found. Some examples:

Original URL Rewritten URL
foo/bar.png foo/bar.png.pagespeed.ic.Hash.png
/bar.png /bar.png.pagespeed.ic.Hash.png
// //
To enable this option, add:

ModPagespeedPreserveUrlRelativity on
pagespeed PreserveUrlRelativity on;
to your configuration file.

Note: This option will be enabled by default in future versions of PageSpeed and eventually the option will be removed entirely.

Configuring the location of static assets

Several filters, including defer_javascript and lazyload_images, require external resources that must be loaded from somewhere. Before, mod_pagespeed would load these files from /mod_pagespeed_static while ngx_pagespeed would load them from /ngx_pagespeed_static. In the default was changed to /pagespeed_static for both platforms and a directive was added to make the path configurable:

ModPagespeedStaticAssetPrefix /custom/static/
pagespeed StaticAssetPrefix /custom/static/;
List outstanding urls on error

When debugging fetching, it can be useful to know how things are failing. If you enable ListOutstandingUrlsOnError then PageSpeed will report a message in the error log at level "error" for every URL fetch in flight when the HTTP stack encounters a system error, e.g. "Connection Refused". To enable this feature, set:

ModPagespeedListOutstandingUrlsOnError on
pagespeed ListOutstandingUrlsOnError on;
Using PageSpeed as a reverse proxy

Typically, PageSpeed is used on an Apache or Nginx server that is already serving its own content. However, PageSpeed can be used with Nginx or Apache as a proxy for another server.

With Apache and mod_pagespeed, mod_proxy can be used to configure Apache as a reverse proxy.

With Nginx and ngx_pagespeed, proxy_pass can be used to configure Nginx as a reverse proxy.


:?: :razz: :sad: :evil: :!: :smile: :oops: :grin: :eek: :shock: :???: :cool: :lol: :mad: :twisted: :roll: :wink: :idea: :arrow: :neutral: :cry: :mrgreen: