Configuring PageSpeed Filters
PageSpeed offers three base "levels" of optimization:
CoreFilters set contains
filters that Google's PageSpeed team believes are safe for most web sites. By
CoreFilters set, as PageSpeed is updated with new
filters, your site will get faster. The
provides a stronger guarantee of safety and is suitable as a default setting
for use with sites that are not aware of PageSpeed.
To disable the
CoreFilters, you can specify
pagespeed RewriteLevel PassThrough
and then enable specific filters with the
The default level is
CoreFilters. The core set of filters
Enabling, Disabling, And Forbidding Specific Filters
To turn off specific filters in the core set, specify:
pagespeed DisableFilters filtera,filterb
For example, if you want to use the core set of filters, but
combine_css, you can use:
pagespeed DisableFilters rewrite_images,combine_css
To turn off specific filters and forbid them from being turned on by query parameters, request headers or in location-specific configuration , specify (for example):
You can use any number of the
ForbidFilters directives, each of which can contain
multiple filter names separated by commas.
EnableFilters configuration file directive allows
specification of one or more filters by name, separated by commas.
You can use any number of
directives, each of which can contain multiple filter names separated
by commas. For example:
The order of the directives in the configuration file is not important. the rewriters are run in the pre-defined order presented in the table: OFB: OptimizeForBandwidth
||Yes||No||Inlines <style> tags comprising only CSS @imports by converting them to equivalent <link> tags.|
||No||No||Externalize large blocks of CSS into a cacheable file.|
||No||No||Externalize large blocks of JS into a cacheable file.|
Moves CSS elements above
Moves CSS elements into
||Yes||No||Combines multiple CSS elements into one.|
||Yes||Yes||Rewrites CSS files to remove excess whitespace and comments, and, if enabled, rewrite or cache-extend images referenced in CSS files. In OptimizeForBandwidth mode, the minification occurs in-place without changing URLs.|
||Yes||No||Rewrites resources referenced in any CSS file that cannot otherwise be parsed and minified.|
||No||No||Rewrite the CSS in style attributes by applying the configured rewrite_css filter to it.|
||Yes||No||Rewrite the CSS in style attributes if it contains the text 'url(' by applying the configured rewrite_css filter to it|
||Yes||No||Inline CSS by flattening all @import rules.|
||No||No||Replace CSS tags with inline versions that include only the CSS used by the page.|
||No||No||Convert synchronous use of Google Analytics API to asynchronous|
||Yes||No||Combines multiple script elements into one.|
||Yes||No||Inlines small CSS files into the HTML document.|
||No||No||Inlines small CSS files used by fonts.googleapis.com into the HTML document.|
||Yes||No||Inlines small JS files into the HTML document.|
||No||No||Cache inlined resources in HTML5 local storage.|
||No||No||Adds the Google Analytics snippet to each HTML page.|
||Yes||Yes||Optimizes images, re-encoding them, removing excess pixels, and inlining small images. In OptimizeForBandwidth mode, the minification occurs in-place without changing URLs.|
||Yes||Yes||Converts larger jpegs to progressive format. Implied by recompress images.|
||Yes||Yes||Converts gif and png images into jpegs if they appear to be less sensitive to compression artifacts and lack alpha transparency. Implied by recompress images.|
||Yes||Yes||Producess lossy webp rather than jpeg images for browsers that support webp. Implied by recompress images.|
||No||No||Replaces gif and png images with webp images on browsers that support the format.|
Implied by rewrite_images. Replaces small images by
||Yes||Yes||Implied by rewrite_images. Recompresses images, removing excess metadata and transforming gifs into pngs.|
||Yes||Yes||Implied by recompress_images. Recompresses jpegs, removing excess metadata.|
||Yes||Yes||Implied by recompress_images. Recompresses pngs, removing excess metadata.|
||Yes||Yes||Implied by recompress_images. Recompresses webps, removing excess metadata.|
||Yes||Yes||Implied by recompress_images. Optimizes gifs to pngs.|
||Yes||Yes||Implied by recompress_images. Strips color profile info from images.|
||Yes||Yes||Implied by recompress_images. Strips EXIF meta data from images.|
||Yes||Yes||Implied by recompress_images. Reduces the color sampling of jpeg images to 4:2:0.|
Implied by rewrite_images. Resizes images
when the corresponding
||Yes||No||Implied by rewrite_images. Resizes an image when the rendered dimensions of the image are smaller than the actual image.|
||No||No||Uses inlined low-quality images as placeholders which will be replaced with original images once the web page is loaded.|
Works just like
Removes excess whitespace in HTML files (avoiding
||No||No||Removes attributes which are not significant according to the HTML spec.|
||Yes||No||Extends cache lifetime of CSS, JS, and image resources that have not otherwise been optimized, by signing URLs with a content hash.|
||Yes||No||Implied by extend_cache. Extends cache lifetime of otherwise unoptimized CSS resources by signing URLs with a content hash.|
||Yes||No||Implied by extend_cache. Extends cache lifetime of otherwise unoptimized images by signing URLs with a content hash.|
||Yes||No||Implied by extend_cache. Extends cache lifetime of otherwise unoptimized scripts by signing URLs with a content hash.|
||No||No||Extends cache lifetime of PDFs by signing URLs with a content hash.|
||No||No||Combine background images in CSS files into one sprite.|
Rewrites the domains of resources not otherwise touched by
PageSpeed, based on
||No||No||Shortens URLs by making them relative to the base URL.|
||No||No||Add default types for <script> and <style> tags if the type attribute is not present and the page is not HTML5. The purpose of this filter is to help ensure that PageSpeed does not break HTML4 validation.|
||No||No||Removes quotes around HTML attributes that are not lexically required.|
Adds a response header for each
||No||No||Loads images when they become visible in the client viewport.|
||No||Yes||Perform browser-dependent in-place resource optimizations.|
Forbidding All Disabled Filters
enable filters for a specific request
using either query parameters or request headers, and you can
enable filters in sub-directories
EnableFilters directive if the server module supports configuring that.
In both cases you can enable filters that are disabled or not explicitly enabled in the configuration file, however there are situations where this is undesirable, such as when a filter has been expressly disabled because it breaks a page, or because a filter imposes too great a load on the server.
All disabled filters can be forced off with:
pagespeed ForbidAllDisabledFilters true
Note that in this context disabled filters means all filters that
are not enabled by the
This directive can be used in location-specific configuration sections.
Checking Which Filters Are Enabled
If you want to see exactly which filters are enabled on a virtual host, you can do so by going to that host's admin or statistics page.
Tuning the Filters
Once the rewriters are selected, some of them may also be tuned. These parameters control the inlining and outlining thresholds of various resources.
CssFlattenMaxBytes 102400 (was 2048 prior to IISpeed 2.0 / PageSpeed 22.214.171.124) CssImageInlineMaxBytes 0 CssInlineMaxBytes 2048 CssOutlineMinBytes 3000 ImageInlineMaxBytes 3072 ImageLimitOptimizedPercent 100 ImageLimitResizeAreaPercent 100 ImageRecompressionQuality 85 ImageResolutionLimitBytes 32000000 JpegRecompressionQuality -1 JpegRecompressionQualityForSmallScreens 70 JpegNumProgressiveScans -1 JpegNumProgressiveScansForSmallScreens -1 WebpRecompressionQuality 80 WebpRecompressionQualityForSmallScreens 70 JsInlineMaxBytes 2048 JsOutlineMinBytes 3000 MaxInlinedPreviewImagesIndex -1 MinImageSizeLowResolutionBytes 3072 RetainComment "[WILDCARD PATTERN]" RewriteRandomDropPercentage 0
Note: The default settings are reasonable and intuitive, but as of this writing (December 2011) have not been experimentally tuned.
These directives can be used in location-specific configuration sections.
Controlling the use of beacons
use a beacon to collect information about the
rewritten page so as to optimize the rewriting process. The beacon is a
filter. The use of this beacon is on by default but it can be disabled using:
pagespeed CriticalImagesBeaconEnabled false
If you disable image beacons but enable filters that use them, the filters will work but not as well as when beacons are enabled.
This directive can be used in all scopes including location-specific configuration sections.
Preserving URLs in HTML
will suppress URL rewriting actions for the respective resource types. Those
filters that require modifications to the URL are disabled by the preserve
Note: Even though resource URLs are unchanged that does not mean that they cannot still be optimized. For instance, InPlaceResourceOptimization still works since it does not alter URLs. Turning on in place resource optimization is recommended when enabling any of the options to preserve URLs. In version 126.96.36.199 and later in place resource optimization is enabled by default.
JsPreserveURLs will forbid the use
of the following filters:
Reducing Load by Randomly Dropping Expensive RewritesTo reduce processing load, PageSpeed can be configured to optimize the most frequently fetched resources, leaving infrequently fetched resources alone. This is accomplished by randomly dropping expensive (CSS and image) rewrites. Frequently fetched resources will have a higher probability of being rewritten than infrequently fetched resources. Over time, frequently accessed resources will be optimized and cached so a page will be fully optimized. Infrequently accessed pages will be left unoptimized or partially optimized, saving CPU time and cache space.
pagespeed RewriteRandomDropPercentage Percent
This is a load-tuning parameter (integer between 0 and 100 inclusive) that controls the percentage of resource rewrites that are randomly dropped. Currently only CSS and image rewrites are randomly dropped, as they are the CPU intensive rewrite tasks. A value of 100 means all such rewrites are dropped and a value of 0 means no rewrites are dropped. A value of 75 means that 75% of image and CSS rewrites (selected at random) are dropped. Do not set this parameter to 100 in order prevent optimization of images and CSS files, it is more efficient to instead disable the image and/or CSS filters.
As an example, if the value is 90 then an image fetched only once will be optimized with 10% probability while an image fetched 50 times will be optimized with 99.65% probability (1 - 0.9^50). You may need to tune this parameter to find a value that provides the right load on your servers and still provides sufficient image and CSS optimization.
Note: Images within CSS files are not randomly dropped as this would lead to partially optimized CSS resources.
Configuring for Multiple Servers
When running PageSpeed on multiple servers, it is important that each have the same configuration file. This ensures that when a browser requests an image or other resource from one server, it will be optimized using the same options that were used to compute the optimized resource when HTML was served. It is helpful to use memcached to share cache between servers as it improves multi-server performance and scalability, but it is still important that the configurations are consistent to get the desired behavior when optimized images are evicted from cache.
Note also that location-specific configuration settings should be consistent between the HTML paths and the resource paths.
In some sites, the URL path layout or network deployment strategy may not allow for consistent configuration between HTML and images. PageSpeed offers a workaround for such sites by encoding relevant configuration settings for each rewritten resource into the URLs:
pagespeed AddOptionsToUrls on
This adds an encoding of the options that are relevant to each rewritten
resource to the URLs. While the produced URLs are larger, this provides a
mechanism to propagate configuration without having to share a configuration
file. For example, a site with image recompression on and JPEG compression set
to 85 would see URLs like
While it is better to have the extra configuration details in the configuration
file, this option offers a fallback plan when that is not practical.
Custom Fetch Headers
When not using LoadFromFile, PageSpeed has to make HTTP requests for sub-resources of a >page in order to rewrite them. Consider the following HTML snippet:
If the image optimization is enabled,
PageSpeed needs to fetch
example.jpg in order to inline,
compress, or otherwise optimize it. If you would like custom headers to be sent
with all sub-resource fetches like this one, you can use
pagespeed CustomFetchHeader CustomHeader CustomHeaderValue pagespeed CustomFetchHeader AnotherCustomHeader AnotherValue
The PageSpeed code base contains a number of additional filters whose use is unsupported. Some of these are experimental; note that using experimental filters is likely to result in crashes or site breakage. Others are used for debugging specific problems with PageSpeed:
|Debugging filter name||Brief Description|
||Removes all script tags from the document.|
Optimizing For Bandwidth
Note: new feature as of IISpeed 2.0 / PageSpeed 188.8.131.52
is designed to reduce latency, incurring a small risk of page breakage.
A related goal, bandwidth reduction, can be achieved with close to zero
risk of web-site breakage:
pagespeed RewriteLevel OptimizeForBandwidth
The bandwidth savings resulting from this option are, of course, dependent
on the source site. Our tests with the default settings
OptimizeForBandwidth indicate an average bandwidth
reduction of roughly 37% over the content of 1000 large web sites with a
client that is capable of displaying webp images, and 25% improvement with
Adding Additional Options
Additional latency optimizations that modify HTML can be layered on
OptimizeForBandwidth by enabling additional
filters, and altering the
up a shared hosting server with
OptimizeForBandwidth in the
root, but where individual sites have
prioritize_critical_css, or simply turned on
following configuration fragment may be used:
As of IISpeed 2.0 / PageSpeed 184.108.40.206 and later,
In Place Resource
is enabled by default. In earlier versions, turning
OptimizeForBandwidth automatically enables In Place
Resource Optimization to optimize the resources without needing to change
their URLs. In these earlier versions, when a VirtualHost overrides
CoreFilers, that turns off
In Place Resource Optimization, but it can be re-enabled explicitly:
pagespeed InPlaceResourceOptimization on