Image Filter and Option Reference

Filter Reference

Convert GIF to PNG

This filter losslessly converts GIF images to PNG, a more recent image format that can generally achieve higher compression than GIF. This filter only converts single-frame GIFs, as PNG only supports single-frame images. Animated GIFs can be converted to the WebP format using the convert_to_webp_animated filter.

Apache:

ModPagespeedEnableFilters convert_gif_to_png

Nginx:

pagespeed EnableFilters convert_gif_to_png;

Convert JPEG to progressive

This filter uses progressive format to encode large (more than 10KB) JPEG images. Progressive format generally yields better compression for large images, and permits incremental display by the browser.

Apache:

ModPagespeedEnableFilters convert_jpeg_to_progressive

Nginx:

pagespeed EnableFilters convert_jpeg_to_progressive;

Convert JPEG to WebP

This filter converts JPEG to lossily-encoded WebP format if the latter is supported by the browser (see list of browsers supporting WebP); otherwise, this filter is ignored.

With this filter enabled, GIF and PNG images can also be converted to lossily-encoded WebP if the configuration allows them to be converted to JPEG (i.e., if convert_gif_to_png and convert_png_to_jpeg are also enabled), and if PageSpeed determines that the images are not sensitive to compression noise.

Note: Before 1.8.31.2, if convert_to_webp_lossless was enabled, GIF and PNG images were converted to losslessly-encoded WebP even if they could be converted to JPEG or lossily-encoded WebP.

Apache:

ModPagespeedEnableFilters convert_jpeg_to_webp

Nginx:

pagespeed EnableFilters convert_jpeg_to_webp;

Convert PNG to JPEG

This filter converts GIF and PNG images to JPEG if they have no transparent pixels and if PageSpeed determines that they are not sensitive to compression noise. The conversion is lossy but the optimized JPEG images are usually substantially smaller than the original.

Note: before 1.8.31.2 mod_pagespeed did not check whether the image was sensitive to compression noise and converted the image to JPEG as long as it did not have transparent pixels.

Apache:

ModPagespeedEnableFilters convert_png_to_jpeg

Nginx:

pagespeed EnableFilters convert_png_to_jpeg;

Convert to WebP animated

This filter converts animated GIF to animated WebP if the latter format is supported by the browser; otherwise, this filter is ignored. Check here for the advantages of animated WebP and a list of supporting browsers.

Note: New feature as of 1.10.33.0

Apache:

ModPagespeedEnableFilters convert_to_webp_animated

Nginx:

pagespeed EnableFilters convert_to_webp_animated;

Convert to WebP lossless

This filter converts PNG and non-animated GIF images to losslessly-encoded WebP if PageSpeed determines that the images are sensitive to compression noise and if the latter format is supported by the browser (see list of browsers supporting WebP); otherwise, this filter is ignored.

Apache:

ModPagespeedEnableFilters convert_to_webp_lossless

Nginx:

pagespeed EnableFilters convert_to_webp_lossless;

Inline images

This filter replaces references to small images by converting them to inline data: URLs, eliminating the need to initiate new connections for fetching the image data.

By default inline_images injects JavaScript that uses a beacon to report back to the server the images that are visible in the client's initial viewport (above-the-fold). It takes a few accesses of a page for the data to be reported back and processed but eventually the above-the-fold images will be identified and inlined, while below-the-fold images will not be inlined; until then all small images will be inlined.

The use of beacons can be disabled using the CriticalImagesBeaconEnabled option. If they are disabled, inline_images will not inject the JavaScript and will revert to inlining small images.

Apache:

ModPagespeedEnableFilters inline_images

Nginx:

pagespeed EnableFilters inline_images;

Inline preview images

This filter replaces each image URL with an inline data: URL of reduced quality; then, after the page's onload event, loads the full-size images. Inlining reduced-quality images makes the page render much faster. As the full-size images load in later, the final experience is a fast page load without loss of detail. See Inline Preview Images for more details.

Insert image dimensions

This filter adds width= and height= attributes to the <img> tags if they are missing. Values for the width= and height= attributes are computed from the image.

Note: This filter may cause stretching or shrinking distortion if you have CSS rules that modify an image's dimensions.

Apache:

ModPagespeedEnableFilters insert_image_dimensions

Nginx:

pagespeed EnableFilters insert_image_dimensions;

Recompress images

This is a filter group consisting of convert_gif_to_png, convert_jpeg_to_progressive, convert_jpeg_to_webp, convert_png_to_jpeg, jpeg_subsampling, recompress_jpeg, recompress_png, recompress_webp, strip_image_color_profile, and strip_image_meta_data.

Note: before 1.11.33.0 convert_png_to_jpeg was not part of recompress_images and needed to be enabled separately.

Apache:

ModPagespeedEnableFilters recompress_images

Nginx:

pagespeed EnableFilters recompress_images;

Recompress JPEG

This filter recompresses JPEG images. Quality for the output image is the minimum of the original image and that specified in the configuration.

Apache:

ModPagespeedEnableFilters recompress_jpeg

Nginx:

pagespeed EnableFilters recompress_jpeg;

Recompress PNG

This filter recompresses PNG images.

Apache:

ModPagespeedEnableFilters recompress_png

Nginx:

pagespeed EnableFilters recompress_png;

Recompress WebP

This filter recompresses single-frame (non-animated) WebP images to the quality specified in the configuration.

Apache:

ModPagespeedEnableFilters recompress_webp

Nginx:

pagespeed EnableFilters recompress_webp;

Reduce JPEG subsampling

This filter uses 4:2:0 chroma subsampling for JPEG images, wherein hue and saturation have only 25% as many samples as brightness. Because human vision is less sensitive to hue and saturation than to brightness, this subsampling can significantly reduce image size with little effect on perception.

Apache:

ModPagespeedEnableFilters jpeg_subsampling

Nginx:

pagespeed EnableFilters jpeg_subsampling;

Resize images

This filter shrinks the dimensions of an image to the width= or height= attribute specified in the <img> tag or in the inline style= attribute.

Note: This filter always strips color profiles and metadata. The resized image may also be recompressed or converted to a new format and quality based on your configuration.

Apache:

ModPagespeedEnableFilters resize_images

Nginx:

pagespeed EnableFilters resize_images;

Resize images to rendered dimensions

This filter shrinks images to their rendered dimensions on the web page. Unlike resize_images, it ignores any width and height attributes specified for the images. If the same image appears more than once on a page it is resized to the largest rendered dimensions.

To report the rendered dimensions back to the server, this filter injects JavaScript code to your pages which beacon the sizes back. Your page needs to be visited several times before the server figures out the rendered dimensions. To use this filter, the CriticalImagesBeaconEnabled filter must be enabled (this is the default).

Note: If both resize_rendered_image_dimensions and resize_images are enabled, resize_rendered_image_dimensions takes precedence.

Note: This filter always strips color profiles and metadata. The resized image may be recompressed or converted to a new format and quality based on your configuration.

Apache:

ModPagespeedEnableFilters resize_rendered_image_dimensions

Nginx:

pagespeed EnableFilters resize_rendered_image_dimensions;

Rewrite images

This is a filter group that includes inline_images, recompress_images, convert_to_webp_lossless, and resize_images.

Apache:

ModPagespeedEnableFilters rewrite_images

Nginx:

pagespeed EnableFilters rewrite_images;

Strip image color profile

This filter strips color profiles from images. The stripped images may also be recompressed or converted to a new format and quality based on your configuration.

Note: Image resizing or format conversion always removes color profiles.

Apache:

ModPagespeedEnableFilters strip_image_color_profile

Nginx:

pagespeed EnableFilters strip_image_color_profile;

Strip image metadata

This filter strips metadata, i.e., data which is not displayed, from images. The stripped images may also be recompressed or converted to a new format and quality based on your configuration.

Note: Image resizing or format conversion always removes metadata.

Apache:

ModPagespeedEnableFilters strip_image_meta_data

Nginx:

pagespeed EnableFilters strip_image_meta_data;

Option Reference

AllowVaryOn

This option controls the response headers PageSpeed may use when deciding how to recompress images in In-Place Resource Optimization mode. PageSpeed uses only the specified headers to tailor the format and quality to the client device and then emits a Vary response header which lists the headers it actually used. If you are using a CDN or caching proxy in front of PageSpeed, it must support the specified headers so the optimized images will be cached correctly in IPRO mode.

Valid values for this option are:

None: This option offers the best caching but disables some of PageSpeed's image optimization features, including WebP transcoding.
Auto: This is equivalent to "Accept, Save-Data" when the request from your user has the Via header (i.e., the request came through a proxy), or "User-Agent, Save-Data" otherwise.
One or more headers from the following, separated by comma: Accept, Save-Data, User-Agent.

The default is Auto.

When you allow PageSpeed to vary on User-Agent, either directly or via Auto, PageSpeed tries all image formats and all image qualities that you have enabled. For example, PageSpeed uses all modes of WebP and qualities for small screens if they apply. However, because of the huge number of user-agents, allowing vary on User-Agent can take up a huge amount of disk space in a cache. Therefore, PageSpeed does not recommend using vary on User-Agent if you use a caching proxy or CDN.

On the other hand, when you allow PageSpeed to vary on Accept, either directly or via Auto, PageSpeed will consider all image formats supported by the Accept header, e.g., the lossy mode of WebP. The Accept header does not indicate whether the device is a small screen, so the qualities for small screens will not be used. The Accept header is not enough to conclude that browser supports the lossless or animated mode of WebP, so they are not used.

When you allow PageSpeed to vary on Save-Data, PageSpeed uses the image qualities that you set for the Save-Data mode if the request has the Save-Data header.

Note: new feature as of 1.11.33.0

Apache:

ModPagespeedAllowVaryOn headers

Nginx:

pagespeed AllowVaryOn headers;

CssImageInlineMaxBytes

This option sets the maximum size in bytes of any image that will be inlined into CSS. For inline CSS in HTML files, the value used is the smaller of MaxBytes or ImageInlineMaxBytes. The default value is 0.

Apache:

ModPagespeedCssImageInlineMaxBytes MaxBytes

Nginx:

pagespeed CssImageInlineMaxBytes MaxBytes;

ImageInlineMaxBytes

This option sets the maximum size in bytes of any image that will be inlined into an HTML file. The default value is 2048.

Apache:

ModPagespeedImageInlineMaxBytes MaxBytes

Nginx:

pagespeed ImageInlineMaxBytes MaxBytes;

ImageJpegNumProgressiveScans

This option sets how many scans (how many groups to divide image data into) are used for progressive JPEGs. More scans allows finer granular increase of display quality, but at the cost of more computation. The range is 1 to 10 and the default is 10.

Apache:

ModPagespeedImageJpegNumProgressiveScans Scans

Nginx:

pagespeed ImageJpegNumProgressiveScans Scans;

ImageJpegNumProgressiveScansForSmallScreens

This option overrides ImageJpegNumProgressiveScans specifically for mobile visitors.

Apache:

ModPagespeedImageJpegNumProgressiveScansForSmallScreens Scans

Nginx:

pagespeed ImageJpegNumProgressiveScansForSmallScreens Scans;

ImageLimitOptimizedPercent

PageSpeed only keeps optimized images whose size after recompression is less than the given percent of the original image size. For example, setting this to 95 will retain an optimized image only if it is at least 5% smaller than the original image it would replace. The default value is 100, meaning any savings at all will cause the optimized image to be used.

Note: Do not set this option to 0 to disable image optimization; disable rewrite_images or the related filters instead. If you set this to 0 PageSpeed will still try to compress all your images, but will throw the output away for showing insufficient compression gains.

Apache:

ModPagespeedImageLimitOptimizedPercent Percent

Nginx:

pagespeed ImageLimitOptimizedPercent Percent;

ImageLimitResizeAreaPercent

PageSpeed only attempts to resize images whose area in pixels after optimization is less than the given percent of the original image area. For example, setting this to 90 will only resize images if the image area shrinks by at least 10%. The default value is 100, meaning any shrinkage at all will cause an image to be resized.

Note: Do not set this option to 0 to disable image resizing, as that just adds computational overhead during page load; disable the resize_images and resize_rendered_image_dimensions filters instead.

Apache:

ModPagespeedImageLimitResizeAreaPercent Percent

Nginx:

pagespeed ImageLimitResizeAreaPercent Percent;

ImageMaxRewritesAtOnce

This option sets the maximum number of images to optimize concurrently. The default value is 8.

To allow optimizing an unlimited number of images concurrently, set this option to "-1". To stop optimizing images, instead disable recompress_images or the related filters.

Note: For backward compatibility, a value of "0" is treated equivalently to "-1", removing the restriction on the number of concurrent image optimizations PageSpeed will attempt.

Apache:

ModPagespeedImageMaxRewritesAtOnce NumImages

Nginx:

pagespeed ImageMaxRewritesAtOnce NumImages;

ImageResolutionLimitBytes

To avoid using too much memory, PageSpeed has a limit on the size of images it will optimize. The limit is expressed in bytes of uncompressed image, with a default of 32 MB. PageSpeed may need four bytes to represent each pixel, so divide by four to compute how many pixels that is. This means with the default settings the largest images PageSpeed will try to optimize are ones with 8 million pixels (8MP). You can calculate the total number of pixels in an image by multiplying its width and height. For example, a 2000x4000 image is 8MP. If you have images that are larger than this limit, and you're comfortable allowing PageSpeed to use the memory it needs to process them, increase ImageResolutionLimitBytes. For example, to allow PageSpeed to process images up to 32 MP (4000x8000) you can set:

Apache:

ModPagespeedImageResolutionLimitBytes 128000000

Nginx:

pagespeed ImageResolutionLimitBytes 128000000;

If you are not comfortable giving more memory to PageSpeed, or you only have a few images that are over 8MP, you might want to consider manually resizing the images instead. The ImageMagick convert command is a convenient way to do this:

convert -resize 8000000@\> input.jpg output.jpg

If input.jpg is larger than 8MP then this command will resize it to just below 8MP while maintaining the aspect ratio. If the image is already smaller than 8MP, convert will leave it alone.

PageSpeed also has a limit on the maximum on-disk size of resources it is willing to optimize, which as of 1.12.34.1 defaults to 16MB. While ImageResolutionLimitBytes is a limit on the uncompressed size of images, PageSpeed will be completely bypassed for any object, not just images, whose on-disk size is larger than MaxCacheableContentLength. You may need to raise that limit as well if you want PageSpeed to optimize larger images.

JpegQualityForSaveData

This option sets the quality for JPEG images if the visitor requests to save data and you decide to honor it. By default, PageSpeed supports Save-Data requests. See AllowVaryOn for information about how to change it. This option overrides JpegRecompressionQuality, unless it is set to -1. The default value is 50.

Note: new feature as of 1.11.33.0

Apache:

ModPagespeedJpegQualityForSaveData Quality

Nginx:

pagespeed JpegQualityForSaveData Quality;

JpegRecompressionQuality

This option sets the quality for JPEG images. It overrides ImageRecompressionQuality, unless it is set to -1. The default value is 85.

Apache:

ModPagespeedJpegRecompressionQuality Quality

Nginx:

pagespeed JpegRecompressionQuality Quality;

JpegRecompressionQualityForSmallScreens

This option sets the quality for JPEG images for users visiting your site from a mobile device. It overrides JpegRecompressionQuality, unless it is set to -1. The default is 70.

Apache:

ModPagespeedJpegRecompressionQualityForSmallScreens Quality

Nginx:

pagespeed JpegRecompressionQualityForSmallScreens Quality;

NoTransformOptimizedImages

By default, PageSpeed-optimized resources are served with response headers that allow proxies and browsers to cache them for a long time, e.g.:

Cache-Control: max-age=31536000

With these headers, proxies are free to recompress images further. This may be beneficial to the overall user experience because it can reduce bandwidth. However, if you already use PageSpeed to compress images as much as you're comfortable with, then you can prevent compliant proxies from further recompressing them by turning on this feature, resulting in responses with header:

Cache-Control: max-age=31536000,no-transform

Note: new feature as of 1.9.32.1

Apache:

ModPagespeedNoTransformOptimizedImages on

Nginx:

pagespeed NoTransformOptimizedImages on;

ProgressiveJpegMinBytes

Progressive JPEG offers better compression for large images, while non-progressive JPEG does better for small images. This option sets the cut-off position for the use of these two formats.

Note: PageSpeed predicts the size of the final compressed JPEG image and then compares the predicted size with this option to determine whether to use progressive format. Due to the accuracy of prediction, some optimized images that are encoded in non-progressive format might be larger than this option, or vice versa.

Apache:

ModPagespeedProgressiveJpegMinBytes min_bytes

Nginx:

pagespeed ProgressiveJpegMinBytes min_bytes;

ImageRecompressionQuality

This option sets the quality for JPEG and WebP formats. It can be overridden by any format-specific or application-specific quality. The default is 85.

Apache:

ModPagespeedImageRecompressionQuality Quality

Nginx:

pagespeed ImageRecompressionQuality Quality;

ServeRewrittenWebpUrlsToAnyAgent

When PageSpeed rewrites an <img> tag in HTML or a background-url in CSS in response to a request from a WebP-capable browser, it may transcode the image to WebP format and rewrites the URL using a .webp extension. If a site visitor copies the .webp image URL and shares it, only WebP-capable browsers will be able to display the image. Sites that place a high value on such URL sharing can make PageSpeed serve PNG/JPEG on .webp URLs by disabling the option ServeRewrittenWebpUrlsToAnyAgent:

Apache:

ModPagespeedServeRewrittenWebpUrlsToAnyAgent off

Nginx:

pagespeed ServeRewrittenWebpUrlsToAnyAgent off;

The default value of ServeRewrittenWebpUrlsToAnyAgent is on because some proxy caches strip the User-Agent and Accept headers when transmitting requests for resources to origin. In that scenario, PageSpeed cannot determine whether the browser requesting the image can display WebP images. Thus it is not possible to have all three of these features at the same time:

Provide the best possible bandwidth and latency experience for visitors using modern browsers
Enable the sharing of URLs between visitors and their friends using older browsers
Use a proxy cache that strips User-Agent and Accept headers

If the first two features are important, the site should use proxy cache technology or CDNs that do not strip User-Agent and Accept. Be sure to check with your proxy cache or CDN vendor to understand their policy on transmitting these headers.

WebpAnimatedRecompressionQuality

This option sets the quality for animated WebP images. It overrides WebpRecompressionQuality and applies to users from both mobile and non-mobile devices, unless it is set to -1. The default is 70.

Note: new feature as of 1.10.33.0

Apache:

ModPagespeedWebpAnimatedRecompressionQuality Quality

Nginx:

pagespeed WebpAnimatedRecompressionQuality Quality;

WebpQualityForSaveData

This option sets the quality for WebP images if both your site and your user have agreed to use save-data. See AllowVaryOn to learn how to enable save-data. This option overrides WebpRecompressionQuality and ModPagespeedWebpAnimatedRecompressionQuality, unless it is set to -1. The default value is 50.

Note: new feature as of 1.11.33.0

Apache:

ModPagespeedWebpQualityForSaveData Quality

Nginx:

pagespeed WebpQualityForSaveData Quality;

WebpRecompressionQuality

This option sets the quality for WebP images. It overrides ImageRecompressionQuality, unless it is set to -1. The default value is 80.

Apache:

ModPagespeedWebpRecompressionQuality Quality

Nginx:

pagespeed WebpRecompressionQuality Quality;

WebpRecompressionQualityForSmallScreens

This option sets the quality for WebP images for users visiting your site from a mobile device. It overrides WebpRecompressionQuality, unless it is set to -1. The default is 70.

Apache:

ModPagespeedWebpRecompressionQualityForSmallScreens Quality

Nginx:

pagespeed WebpRecompressionQualityForSmallScreens Quality;