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 pagespeed_module> .... </IfModule>
mod_pagespeed contains three handlers:
- A default handler to serve optimized resources
- mod_pagespeed_statistics: shows server statistics since startup, from which one can compute average latency, and thereby measure the effectiveness of various rewriting passes
- 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 </Location> # This handles the client-side instrumentation callbacks which are injected # by the add_instrumentation filter. <Location /mod_pagespeed_beacon> SetHandler mod_pagespeed_beacon </Location>
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:
These directives can be used in
.htaccess files and
Turning ON mod_pagespeed
To turn mod_pagespeed ON, insert as the top line of pagespeed.conf:
Support for Apache 2.4.x
Note: New feature as of 0.10.22.3
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
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
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 </IfModule> <IfVersion < 2.4> LoadModule pagespeed_module /usr/lib/apache2/modules/mod_pagespeed.so </IfVersion> <IfVersion >= 2.4.2> LoadModule pagespeed_module /usr/lib/apache2/modules/mod_pagespeed_ap24.so </IfVersion>to auto-detect. Builds against system Apache headers will only be compatible with that version family, and will always produce a single module named
Respecting Vary Headers
Note: New feature as of 0.9.18.1
In order to maximize the number of resources that
can rewrite, by default the module does not respect
Vary: User-Agent and other
Vary headers on
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
HTML files, regardless of this setting.
If a site has resources that legitimately vary on
on some other attribute, then in order to preserve that behavior, you must
to your configuration file.
Please note that turning on this option will disable optimization of any
Vary headers, apart from
Lower-casing HTML element and attribute names
Note: New feature as of 0.9.16.1
In general, mod_pagespeed knows whether a document is HTML or not
Content-Type tags in HTTP headers,
DOCTYPE. However, many web sites have
Content-Type: text/html for resources that are actually
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:
These directives can be used in
.htaccess files and
This switch is only risky in the presence of XML files that are
incorrectly served with
Lower-casing XML element and attribute may affect whatever software is
reading the XML.
Preserving HTML caching headers
Note: New feature as of 0.10.20.1
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:
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 0.10.22.3
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
.htaccess file can be used to control most of the
directives in mod_pagespeed. This is functionally equivalent to
specifying mod_pagespeed directives in
<Directory> scope. Note, however, that the
file-matching implied by the
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
ModPagespeedDisallow directives described above, using
full paths or wildcards in those directives.
Directives that cannot be used with
ModPagespeedFetchWithGzip ModPagespeedFetcherTimeoutMs ModPagespeedFileCacheCleanIntervalMs ModPagespeedFileCachePath ModPagespeedFileCacheSizeKb ModPagespeedGeneratedFilePrefix ModPagespeedLRUCacheByteLimit ModPagespeedLRUCacheKbPerProcess ModPagespeedLoadFromFile ModPagespeedNumRewriteThreads ModPagespeedNumExpensiveRewriteThreads ModPagespeedXHeaderValue
Directives that can be used with
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
Apache HTTP Server Documentation:
Note: You should avoid using
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