mod_pagespeed Installation and Configuration

Installation Tips

mod_pagespeed is available in binary form as as Debian package for Linux distributions such as Ubuntu, installable with dpkg. It is also available as an RPM package for CentOS or compatible Linux distributions.

You can browse or check out the source code in the open source repository.

Configuring the Module

mod_pagespeed contains an Apache "output filter" plus several content handlers.

Note: The location of the configuration file is dependent on the Linux distribution on which mod_pagespeed is installed.

On Debian/Ubuntu Linux distributions, the directory will be:


On CentOS/Fedora, the directory will be:


The mod_pagespeed configuration directives should be wrapped inside an IfModule:

<IfModule pagespeed_module>

Configuring Handlers

mod_pagespeed contains three handlers:

  1. A default handler to serve optimized resources
  2. mod_pagespeed_statistics: shows server statistics since startup, from which one can compute average latency, and thereby measure the effectiveness of various rewriting passes
  3. mod_pagespeed_beacon: part of the infrastructure we provide for measuring page latency.

The following settings for the handlers can be used as a guideline:

    # Uncomment the following line if you want to disable statistics entirely.
    # ModPagespeedStatistics off

    # This page shows statistics about the mod_pagespeed module.
    <Location /mod_pagespeed_statistics>
        Order allow,deny
        # One may insert other "Allow from" lines to add hosts that are
        # allowed to look at generated statistics.  Another possibility is
        # to comment out the "Order" and "Allow" options from the config
        # file, to allow any client that can reach the server to examine
        # statistics.  This might be appropriate in an experimental setup or
        # if the Apache server is protected by a reverse proxy that will
        # filter URLs to avoid exposing these statistics, which may
        # reveal site metrics that should not be shared otherwise.
        Allow from localhost
        SetHandler mod_pagespeed_statistics

    # This handles the client-side instrumentation callbacks which are injected
    # by the add_instrumentation filter.
    <Location /mod_pagespeed_beacon>
          SetHandler mod_pagespeed_beacon

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

Turning OFF mod_pagespeed

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

ModPagespeed off

These directives can be used in .htaccess files and <Directory> scopes.

Turning ON mod_pagespeed

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

ModPagespeed on

Support for Apache 2.4.x

Note: New feature as of

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, mod_pagespeed_ap24.so instead of the usual mod_pagespeed.so. 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:

<IfModule !mod_version.c>
  LoadModule version_module /usr/lib/apache2/modules/mod_version.so

<IfVersion < 2.4>
  LoadModule pagespeed_module /usr/lib/apache2/modules/mod_pagespeed.so
<IfVersion >= 2.4.2>
  LoadModule pagespeed_module /usr/lib/apache2/modules/mod_pagespeed_ap24.so
to auto-detect. Builds against system Apache headers will only be compatible with that version family, and will always produce a single module named mod_pagespeed.so.

Respecting Vary Headers

Note: New feature as of

In order to maximize the number of resources that mod_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, mod_pagespeed is able to keep the size of the cache down. mod_pagespeed will always respect Vary: Accept-Encoding, regardless of this setting. mod_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

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.

Lower-casing HTML element and attribute names

Note: New feature as of

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

In general, mod_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 mod_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, mod_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

These directives can be used in .htaccess files and <Directory> scopes.


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

Note: New feature as of

By default, mod_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 mod_pagespeed to leave the original HTML caching headers you can add:

ModPagespeedModifyCachingHeaders off

Note: We do not suggest you turn this option off. It breaks mod_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 X-Mod-Pagespeed header

Note: New feature as of

By default, mod_pagespeed adds an X-Mod-Pagespeed header with a value of the version of mod_pagespeed being used. This directive lets you specify the value to use instead:

ModPagespeedXHeaderValue "Powered By mod_pagespeed"

Note: You cannot suppress the injection of this header. This is because it is used to prevent infinite loops and unnecessary rewrites when mod_pagespeed fetches resources from an origin that also uses mod_pagespeed.

.htaccess files and Directory scopes

The .htaccess file can be used to control most of the directives in mod_pagespeed. This is functionally equivalent to specifying mod_pagespeed directives in a <Directory> scope. Note, however, that the file-matching implied by the <Directory> scope, or the directory of the .htaccess file, 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 ModPagespeedAllow and ModPagespeedDisallow directives described above, using full paths or wildcards in those directives.

Directives that cannot be used with .htaccess and <Directory> scope


Directives that can be used with .htaccess and <Directory> scope


The advantage of .htaccess is that it can be used in environments where the site administrator does not have access to the Apache 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 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 <Directory> block, as it will have the same effect with better performance.

Another mechanism available to configure mod_pagespeed for multiple distinct sites is VirtualHost.