+1 (617) 7782998 |

Configuring PageSpeed Filters

Optimization Level

PageSpeed offers three base "levels" of optimization: PassThrough, CoreFilters, and OptimizeForBandwidth. The CoreFilters set contains filters that Google's PageSpeed team believes are safe for most web sites. By using the CoreFilters set, as PageSpeed is updated with new filters, your site will get faster. The OptimizeForBandwidth setting 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 EnableFilters directive. The default level is CoreFilters. The core set of filters contains:


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 specifically disable rewrite_images and 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):

pagespeed ForbidFilters rewrite_css,rewrite_javascript

You can use any number of the DisableFilters and/or ForbidFilters directives, each of which can contain multiple filter names separated by commas.

The EnableFilters configuration file directive allows specification of one or more filters by name, separated by commas. You can use any number of EnableFilters directives, each of which can contain multiple filter names separated by commas. For example:

pagespeed RewriteLevel PassThrough
pagespeed EnableFilters combine_css,extend_cache,rewrite_images
pagespeed EnableFilters rewrite_css,rewrite_javascript

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:

[1] OFB: OptimizeForBandwidth
Optimization Core OFB[1] Brief Description
add_head Yes No Adds a <head> element to the document if not already present.
combine_heads No No Combines multiple <head> elements found in document into one.
inline_import_to_link Yes No Inlines <style> tags comprising only CSS @imports by converting them to equivalent <link> tags.
outline_css No No Externalize large blocks of CSS into a cacheable file.
outline_javascript No No Externalize large blocks of JS into a cacheable file.
move_css_above_scripts No No Moves CSS elements above <script> tags.
move_css_to_head No No Moves CSS elements into the <head>.
combine_css Yes No Combines multiple CSS elements into one.
rewrite_css 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.
fallback_rewrite_css_urls Yes No Rewrites resources referenced in any CSS file that cannot otherwise be parsed and minified.
rewrite_style_attributes No No Rewrite the CSS in style attributes by applying the configured rewrite_css filter to it.
rewrite_style_attributes_with_url Yes No Rewrite the CSS in style attributes if it contains the text 'url(' by applying the configured rewrite_css filter to it
flatten_css_imports Yes No Inline CSS by flattening all @import rules.
prioritize_critical_css No No Replace CSS tags with inline versions that include only the CSS used by the page.
make_google_analytics_async No No Convert synchronous use of Google Analytics API to asynchronous
rewrite_javascript Yes Yes Rewrites JavaScript files to remove excess whitespace and comments. In OptimizeForBandwidth mode, the minification occurs in-place without changing URLs.
rewrite_javascript_external Yes Yes Implied by rewrite_javascript. Rewrites JavaScript external files to remove excess whitespace and comments. In OptimizeForBandwidth mode, the minification occurs in-place without changing URLs.
rewrite_javascript_inline Yes Yes Implied by rewrite_javascript. Rewrites inline JavaScript blocks to remove excess whitespace and comments.
include_js_source_maps No No Adds source maps to rewritten JavaScript files.
combine_javascript Yes No Combines multiple script elements into one.
canonicalize_javascript_libraries No No Redirects JavaScript libraries to a JavaScript hosting service.
inline_css Yes No Inlines small CSS files into the HTML document.
inline_google_font_css No No Inlines small CSS files used by into the HTML document.
inline_javascript Yes No Inlines small JS files into the HTML document.
local_storage_cache No No Cache inlined resources in HTML5 local storage.
insert_ga No No Adds the Google Analytics snippet to each HTML page.
rewrite_images 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.
convert_jpeg_to_progressive Yes Yes Converts larger jpegs to progressive format. Implied by recompress images.
convert_png_to_jpeg 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.
convert_jpeg_to_webp Yes Yes Producess lossy webp rather than jpeg images for browsers that support webp. Implied by recompress images.
convert_to_webp_lossless No No Replaces gif and png images with webp images on browsers that support the format.
insert_image_dimensions No No Adds width and height attributes to <img> tags that lack them.
inline_images Yes No Implied by rewrite_images. Replaces small images by data: urls.
recompress_images Yes Yes Implied by rewrite_images. Recompresses images, removing excess metadata and transforming gifs into pngs.
recompress_jpeg Yes Yes Implied by recompress_images. Recompresses jpegs, removing excess metadata.
recompress_png Yes Yes Implied by recompress_images. Recompresses pngs, removing excess metadata.
recompress_webp Yes Yes Implied by recompress_images. Recompresses webps, removing excess metadata.
convert_gif_to_png Yes Yes Implied by recompress_images. Optimizes gifs to pngs.
strip_image_color_profile Yes Yes Implied by recompress_images. Strips color profile info from images.
strip_image_meta_data Yes Yes Implied by recompress_images. Strips EXIF meta data from images.
jpeg_sampling Yes Yes Implied by recompress_images. Reduces the color sampling of jpeg images to 4:2:0.
resize_images Yes No Implied by rewrite_images. Resizes images when the corresponding <img> tag specifies a smaller width and height.
resize_rendered_image_dimensions Yes No Implied by rewrite_images. Resizes an image when the rendered dimensions of the image are smaller than the actual image.
inline_preview_images No No Uses inlined low-quality images as placeholders which will be replaced with original images once the web page is loaded.
resize_mobile_images No No Works just like inline_preview_images, but uses smaller placeholder images and only serves them to mobile browsers.
remove_comments No No Removes comments in HTML files (but not in inline JavaScript or CSS).
collapse_whitespace No No Removes excess whitespace in HTML files (avoiding <pre>, <script>, <style>, and <textarea>).
elide_attributes No No Removes attributes which are not significant according to the HTML spec.
extend_cache Yes No Extends cache lifetime of CSS, JS, and image resources that have not otherwise been optimized, by signing URLs with a content hash.
extend_cache_css Yes No Implied by extend_cache. Extends cache lifetime of otherwise unoptimized CSS resources by signing URLs with a content hash.
extend_cache_images Yes No Implied by extend_cache. Extends cache lifetime of otherwise unoptimized images by signing URLs with a content hash.
extend_cache_scripts Yes No Implied by extend_cache. Extends cache lifetime of otherwise unoptimized scripts by signing URLs with a content hash.
extend_cache_pdfs No No Extends cache lifetime of PDFs by signing URLs with a content hash.
sprite_images No No Combine background images in CSS files into one sprite.
rewrite_domains No No Rewrites the domains of resources not otherwise touched by PageSpeed, based on MapRewriteDomain and ShardDomain settings in the config file.
trim_urls No No Shortens URLs by making them relative to the base URL.
pedantic 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.
remove_quotes No No Removes quotes around HTML attributes that are not lexically required.
add_instrumentation No No Adds JavaScript to page to measure latency and send back to the server.
convert_meta_tags Yes No Adds a response header for each meta tag with an http-equiv attribute. IISpeed doesn't support this filter.
defer_javascript No No Defers the execution of JavaScript in HTML until page load complete.
dedup_inlined_images No No Replaces repeated inlined images with JavaScript that loads the image from the first occurence of the image.
lazyload_images No No Loads images when they become visible in the client viewport.
insert_dns_prefetch No No Inserts <link rel="dns-prefetch" href="//"> tags to reduce DNS resolution time.
in_place_optimize_for_browser No Yes Perform browser-dependent in-place resource optimizations.

Forbidding All Disabled Filters

You can enable filters for a specific request using either query parameters or request headers, and you can enable filters in sub-directories using the 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 RewriteLevel or EnableFilters directives.

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
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

The lazyload_images, inline_preview_images, and inline_images filters, use a beacon to collect information about the rewritten page so as to optimize the rewriting process. The beacon is a POST request sent back by JavaScript inserted into the page by the 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

PageSpeed filters often modify the URLs of resources in HTML pages. This is generally harmless but it has the potential to break pages whose JavaScript expects to read or modify the URLs in the page.

ImagePreserveURLs, CssPreserveURLs, and JsPreserveURLs will suppress URL rewriting actions for the respective resource types. Those filters that require modifications to the URL are disabled by the preserve directives.

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 and later in place resource optimization is enabled by default.

Enabling ImagePreserveURLs will forbid the use of the following filters: inline_preview_images, lazyload_images, extend_cache_images, inline_images, and sprite_images.

Enabling CssPreserveURLs will forbid the use of the following filters: combine_css, extend_cache_css, inline_css, inline_import_to_link, and outline_css.

Enabling JsPreserveURLs will forbid the use of the following filters: canonicalize_javascript_libraries, combine_javascript, defer_javascript, extend_cache_scripts, inline_javascript, and outline_javascript.

Reducing Load by Randomly Dropping Expensive Rewrites

To 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:

<img src="example.jpg">

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 the CustomFetchHeader directive:

pagespeed CustomFetchHeader CustomHeader CustomHeaderValue
pagespeed CustomFetchHeader AnotherCustomHeader AnotherValue

Unsupported Filters

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
add_base_tag Adds a <base> element to the beginning of the <head> that reflects the base url PageSpeed is using to resolve relative url references in the page.
debug Adds comments to the page describing actions by certain filters, and attempts to serve JavaScript injected by PageSpeed in source form rather than compiled and minified.
deterministic_js Attempts to provide deterministic JavaScript behavior on each page, for example by replacing the timer and random number generator with functions that return the same sequence of values on every page load.
strip_scripts Removes all script tags from the document.

Optimizing For Bandwidth

Note: new feature as of IISpeed 2.0 / PageSpeed

PageSpeed's default RewriteLevel of CoreFilters 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

This option is suitable for use in a root configuration at a hosting service, CDN, or multi-site setup. In this mode, PageSpeed does not alter HTML at all. It compresses and transcodes images in place, and minifies JavaScript and CSS. By avoiding changes to URL syntax and to HTML, the potential problem of user-written JavaScript encountering unexpected DOM elements is elimimated. There is still latency benefit due to the reduced size of resources, as well as substantial bandwidth reduction.

Bandwidth Savings

The bandwidth savings resulting from this option are, of course, dependent on the source site. Our tests with the default settings for 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 older clients.

Adding Additional Options

Additional latency optimizations that modify HTML can be layered on top of OptimizeForBandwidth by enabling additional filters, and altering the Preserve URL settings for CSS, images, or JavaScript. For example, to set up a shared hosting server with OptimizeForBandwidth in the root, but where individual sites have added inline_javascript, lazyload_images and prioritize_critical_css, or simply turned on CoreFilters, the following configuration fragment may be used:

# In root configuration:
pagespeed RewriteLevel OptimizeForBandwidth

# Site or host specific configuration, prioritize_above_the_fold
pagespeed EnableFilters inline_javascript,prioritize_critical_css,inline_preview_images

# Site or host specific configuration, preserve_css_urls_off
pagespeed CssPreserveURLs off

# Site or host specific configuration, core filters
pagespeed RewriteLevel CoreFilters

As of IISpeed 2.0 / PageSpeed and later, In Place Resource Optimization is enabled by default. In earlier versions, turning on 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 the RewriteLevel to CoreFilers, that turns off In Place Resource Optimization, but it can be re-enabled explicitly:

pagespeed InPlaceResourceOptimization on

Share View Comments
Some content on this website represents a modified version of the official Google PageSpeed documentation