Image Filters

Overview

mod_pagespeed 1.1 includes image filters for recompression, format conversion, resizing, and inlining that to reduce page weight and improve load times. The master filter rewrite_images is a CoreFilter and enables several sub-filters by default. Additional image filters can be enabled individually for finer control.

IIS syntax

On IIS, use the same filter names with the pagespeed prefix in pagespeed.config (no semicolons):

pagespeed EnableFilters rewrite_images
pagespeed ImageRecompressionQuality 75

See IIS Configuration for the full file format reference.

Quick reference

Filter	Core	OFB	Description	Safe
rewrite_images	Yes	-	Master filter; enables recompress, resize, inline sub-filters	Yes
recompress_images	via rewrite_images	Yes	Losslessly recompress all images	Yes
recompress_jpeg	via rewrite_images	Yes	Recompress JPEG images	Yes
recompress_png	via rewrite_images	Yes	Recompress PNG images	Yes
recompress_webp	via rewrite_images	Yes	Recompress WebP images	Yes
convert_jpeg_to_progressive	via rewrite_images	Yes	Convert large JPEGs to progressive encoding	Yes
convert_jpeg_to_webp	via rewrite_images	Yes	Serve WebP to capable browsers	Yes
convert_png_to_jpeg	via rewrite_images	Yes	Convert opaque PNGs to JPEG	Yes
convert_gif_to_png	via rewrite_images	Yes	Convert GIF to PNG	Yes
convert_to_webp_animated	No	No	Convert animated GIF to animated WebP	Test first
convert_to_webp_lossless	No	No	Use lossless WebP instead of lossy	Test first
strip_image_color_profile	via rewrite_images	Yes	Remove ICC color profiles	Yes
strip_image_meta_data	via rewrite_images	Yes	Remove EXIF and other metadata	Yes
jpeg_sampling	via rewrite_images	Yes	Downsample JPEG color channels	Yes
resize_images	via rewrite_images	-	Resize images to declared width/height	Yes
resize_rendered_image_dimensions	via rewrite_images	-	Resize images to rendered dimensions via JS	Test first
inline_images	via rewrite_images	-	Inline small images as data: URIs	Yes
responsive_images	No	No	Generate srcset attributes	Test first
lazyload_images	No	No	Defer offscreen image loading	Test first
inline_preview_images	No	No	Show low-quality placeholder before full load	Test first
resize_mobile_images	No	No	Serve smaller images to mobile devices	Test first
dedup_inlined_images	No	No	Deduplicate repeated inlined images	Yes
sprite_images	No	No	Combine CSS background images into sprites	Test first
insert_image_dimensions	No	No	Add width/height to <img> tags	Test first
in_place_optimize_for_browser	No	Yes	Serve browser-specific formats via Vary: Accept	Test first

Core = enabled by default in the CoreFilters set. OFB = enabled by OptimizeForBandwidth mode.

Master filter: rewrite_images {#rewrite_images}

What it does

rewrite_images is the master image optimization CoreFilter. Enabling it activates a family of sub-filters that recompress images, convert formats where beneficial, resize to declared dimensions, and inline small images as data: URIs.

Sub-filters enabled by default

When rewrite_images is active, the following sub-filters are enabled automatically:

• recompress_images (and its sub-filters: recompress_jpeg, recompress_png, recompress_webp)
• convert_jpeg_to_progressive
• convert_jpeg_to_webp
• convert_png_to_jpeg
• convert_gif_to_png
• strip_image_color_profile
• strip_image_meta_data
• jpeg_sampling
• resize_images
• inline_images

Directives

Apache:

ModPagespeedEnableFilters rewrite_images

nginx:

pagespeed EnableFilters rewrite_images;

To disable a specific sub-filter while keeping rewrite_images active:

Apache:

ModPagespeedEnableFilters rewrite_images
ModPagespeedDisableFilters convert_jpeg_to_webp

nginx:

pagespeed EnableFilters rewrite_images;
pagespeed DisableFilters convert_jpeg_to_webp;

Recompression filters {#recompress_images}

What they do

The recompression filters (recompress_images, recompress_jpeg, recompress_png, recompress_webp) reduce image file size by re-encoding images at an optimal quality level. These filters preserve visual quality while removing encoding inefficiencies.

recompress_images is a convenience filter that enables recompress_jpeg, recompress_png, and recompress_webp together.

Directives

Apache:

ModPagespeedEnableFilters recompress_images
# Or individually:
ModPagespeedEnableFilters recompress_jpeg,recompress_png,recompress_webp

nginx:

pagespeed EnableFilters recompress_images;
# Or individually:
pagespeed EnableFilters recompress_jpeg,recompress_png,recompress_webp;

Configuration

Parameter	Default	Description
ImageRecompressionQuality	85	General quality level for recompressed images (0-100)
JpegRecompressionQuality	-1	JPEG-specific quality; -1 uses ImageRecompressionQuality
WebpRecompressionQuality	80	WebP quality level

Apache:

ModPagespeedImageRecompressionQuality 85
ModPagespeedJpegRecompressionQuality 75

nginx:

pagespeed ImageRecompressionQuality 85;
pagespeed JpegRecompressionQuality 75;

Risks

Recompression is lossy. Setting quality too low produces visible artifacts. The default values are conservative and safe for most content. Photographic content can tolerate lower quality than screenshots or text-heavy images.

Format conversion filters {#convert_formats}

What they do

Format conversion filters serve images in the most efficient format for each browser and image type:

• convert_jpeg_to_progressive converts large baseline JPEGs to progressive encoding. Progressive JPEGs render incrementally and are often smaller for images above ~10 KB.
• convert_jpeg_to_webp serves WebP versions of JPEG images to browsers that send Accept: image/webp. The original JPEG is preserved for other browsers.
• convert_png_to_jpeg converts PNG images with no alpha channel (fully opaque) to JPEG, which is typically much smaller for photographic content.
• convert_gif_to_png converts non-animated GIF images to PNG, which uses better compression.
• convert_to_webp_animated converts animated GIF images to animated WebP. Not a CoreFilter.
• convert_to_webp_lossless uses lossless WebP encoding instead of lossy. Produces larger files than lossy WebP but preserves every pixel. Not a CoreFilter.

Directives

Apache:

ModPagespeedEnableFilters convert_jpeg_to_progressive
ModPagespeedEnableFilters convert_jpeg_to_webp
ModPagespeedEnableFilters convert_png_to_jpeg
ModPagespeedEnableFilters convert_gif_to_png
ModPagespeedEnableFilters convert_to_webp_animated
ModPagespeedEnableFilters convert_to_webp_lossless

nginx:

pagespeed EnableFilters convert_jpeg_to_progressive;
pagespeed EnableFilters convert_jpeg_to_webp;
pagespeed EnableFilters convert_png_to_jpeg;
pagespeed EnableFilters convert_gif_to_png;
pagespeed EnableFilters convert_to_webp_animated;
pagespeed EnableFilters convert_to_webp_lossless;

Configuration

Parameter	Default	Description
JpegProgressiveMinBytes	10240	Minimum JPEG size before converting to progressive
WebpRecompressionQuality	80	Quality for lossy WebP conversion
WebpAnimatedRecompressionQuality	70	Quality for animated WebP conversion

Risks

• convert_png_to_jpeg drops the alpha channel on opaque PNGs. mod_pagespeed checks for alpha before converting, but semi-transparent pixels at the boundary may cause subtle edge artifacts.
• convert_jpeg_to_webp relies on the browser’s Accept header. Some CDNs strip or ignore Vary: Accept, which can cause incorrect format delivery. Test with your CDN configuration.
• convert_to_webp_animated can produce large files for complex animations. Verify output sizes.

Image stripping filters {#strip_metadata}

What they do

• strip_image_color_profile removes embedded ICC color profiles from images. Most web browsers ignore ICC profiles, and they can add tens of kilobytes to a file.
• strip_image_meta_data removes EXIF, XMP, and other metadata from images. This includes camera information, GPS coordinates, thumbnails, and editing history.
• jpeg_sampling downsamples JPEG chroma channels (4:2:0 subsampling), reducing file size with minimal visual impact on photographic content.

Directives

Apache:

ModPagespeedEnableFilters strip_image_color_profile
ModPagespeedEnableFilters strip_image_meta_data
ModPagespeedEnableFilters jpeg_sampling

nginx:

pagespeed EnableFilters strip_image_color_profile;
pagespeed EnableFilters strip_image_meta_data;
pagespeed EnableFilters jpeg_sampling;

Risks

• Stripping color profiles can cause subtle color shifts on wide-gamut displays or for images authored in non-sRGB color spaces. This affects a small fraction of web images.
• Stripping metadata removes copyright and attribution information embedded in the file. The metadata is removed from the served variant only; original files on disk are not modified.

Resizing filters {#resize_images}

What they do

• resize_images resizes images on the server to match the width and height attributes declared in the <img> tag. If an image is 2000x1500 but displayed at 400x300, mod_pagespeed serves a 400x300 variant.
• resize_rendered_image_dimensions injects JavaScript that reports each image’s actual rendered dimensions on the client. On subsequent requests, mod_pagespeed resizes to the rendered size. Requires two page loads to take effect.
• insert_image_dimensions adds explicit width and height attributes to <img> tags that lack them. This prevents layout shifts (CLS) but does not resize the image file itself.

Directives

Apache:

ModPagespeedEnableFilters resize_images
ModPagespeedEnableFilters resize_rendered_image_dimensions
ModPagespeedEnableFilters insert_image_dimensions

nginx:

pagespeed EnableFilters resize_images;
pagespeed EnableFilters resize_rendered_image_dimensions;
pagespeed EnableFilters insert_image_dimensions;

Configuration

Parameter	Default	Description
ImageLimitResizeAreaPercent	100	Only resize if the result is this percentage of the original area or less

Risks

• resize_images only works when width and height are present on the <img> tag. Images sized purely by CSS are not resized.
• resize_rendered_image_dimensions injects JavaScript and requires two page loads. The first load serves the original image.
• insert_image_dimensions can break responsive layouts that rely on the absence of explicit dimensions. Test with your CSS.

Inline and preview filters {#inline_images}

What they do

• inline_images replaces small image references with data: URIs, eliminating the HTTP request. Only images below ImageInlineMaxBytes are inlined.
• inline_preview_images replaces full-size images with a low-quality inline placeholder that loads instantly, then swaps in the full image via JavaScript.
• dedup_inlined_images replaces repeated inline data: URIs on the same page with JavaScript references to the first occurrence, reducing HTML size.
• resize_mobile_images serves smaller images to mobile devices based on the User-Agent header.

Directives

Apache:

ModPagespeedEnableFilters inline_images
ModPagespeedEnableFilters inline_preview_images
ModPagespeedEnableFilters dedup_inlined_images
ModPagespeedEnableFilters resize_mobile_images

nginx:

pagespeed EnableFilters inline_images;
pagespeed EnableFilters inline_preview_images;
pagespeed EnableFilters dedup_inlined_images;
pagespeed EnableFilters resize_mobile_images;

Configuration

Parameter	Default	Description
ImageInlineMaxBytes	3072	Maximum image size in bytes to inline as a data: URI

Apache:

ModPagespeedImageInlineMaxBytes 4096

nginx:

pagespeed ImageInlineMaxBytes 4096;

Risks

• Inlining increases HTML size. Inlined images are not cached separately by the browser. Set ImageInlineMaxBytes conservatively.
• inline_preview_images adds JavaScript and a visible quality transition. Users see a blurry image before the full-resolution variant loads.
• resize_mobile_images relies on User-Agent detection. Incorrect UA classification can serve wrong-sized images.

Lazy loading: lazyload_images {#lazyload_images}

What it does

lazyload_images defers loading of images that are below the fold. Images are loaded via JavaScript as the user scrolls them into view, reducing initial page weight and request count.

Directives

Apache:

ModPagespeedEnableFilters lazyload_images

nginx:

pagespeed EnableFilters lazyload_images;

Configuration

To disable lazy loading for a specific image, add the data-pagespeed-no-defer attribute:

<img src="hero.jpg" data-pagespeed-no-defer />

Risks

• Modern browsers support native loading="lazy" on <img> tags. Using both mod_pagespeed lazy loading and native lazy loading simultaneously can cause double-deferred loading. Choose one approach.
• JavaScript-based lazy loading can interfere with image-dependent layout calculations, print rendering, and automated testing tools.
• Images that are immediately visible (above the fold) should not be lazy loaded. mod_pagespeed uses heuristics to detect above-fold images, but these heuristics are imperfect.

Responsive images {#responsive_images}

What it does

responsive_images generates multiple resized versions of each image and adds srcset attributes to <img> tags, allowing the browser to select the optimal resolution for the current viewport and device pixel ratio.

Directives

Apache:

ModPagespeedEnableFilters responsive_images

nginx:

pagespeed EnableFilters responsive_images;

Configuration

To control which resolutions are generated, use ResponsiveImageDensities:

Apache:

ModPagespeedResponsiveImageDensities "1x,1.5x,2x,3x"

nginx:

pagespeed ResponsiveImageDensities "1x,1.5x,2x,3x";

Risks

• Generating multiple variants per image increases storage and cache requirements on the server.
• If images have many density variants, the total bytes served across all variants can exceed the original single image. Monitor cache size and bandwidth.
• Requires width and height attributes on <img> tags to calculate variant dimensions.

Sprite images {#sprite_images}

What it does

sprite_images combines multiple CSS background images into a single sprite sheet and rewrites the CSS background-position values to reference the correct region within the sprite.

Directives

Apache:

ModPagespeedEnableFilters sprite_images

nginx:

pagespeed EnableFilters sprite_images;

Risks

• With HTTP/2 multiplexing, the latency benefit of spriting is minimal. Multiple small requests over a single connection are often as fast as one large sprite request.
• Spriting increases cache invalidation scope: changing one image invalidates the entire sprite.
• Only CSS background-image references are sprited. Inline <img> tags are not affected.

In-place browser optimization {#in_place_optimize_for_browser}

What it does

in_place_optimize_for_browser optimizes images served from their original URL (without rewriting the HTML) by using the browser’s Accept header to serve the best format. For example, a .jpg URL can serve WebP content to browsers that support it. The response includes Vary: Accept to ensure correct caching.

This filter is enabled by the OptimizeForBandwidth mode but is not a CoreFilter.

Directives

Apache:

ModPagespeedEnableFilters in_place_optimize_for_browser

nginx:

pagespeed EnableFilters in_place_optimize_for_browser;

Risks

• The Vary: Accept header can reduce CDN cache hit rates. Many CDNs handle Vary correctly, but verify with your provider.
• Some proxy servers do not respect Vary headers and may serve the wrong format to clients.

Tuning parameters

Parameter	Default	Description
ImageRecompressionQuality	85	General quality for recompressed images (0-100)
JpegRecompressionQuality	-1	JPEG-specific quality; -1 uses ImageRecompressionQuality
WebpRecompressionQuality	80	WebP quality level
WebpAnimatedRecompressionQuality	70	Animated WebP quality level
ImageInlineMaxBytes	3072	Maximum image size in bytes to inline as a data: URI
ImageLimitOptimizedPercent	100	Only serve the optimized image if it is smaller by this percentage
ImageLimitResizeAreaPercent	100	Limit on resize area relative to original
ImageResolutionLimitBytes	32000000	Maximum image resolution in bytes to attempt to optimize
ImageMaxRewritesAtOnce	8	Server-wide limit on parallel image optimizations

Apache:

ModPagespeedImageRecompressionQuality 85
ModPagespeedJpegRecompressionQuality 75
ModPagespeedWebpRecompressionQuality 80
ModPagespeedWebpAnimatedRecompressionQuality 70
ModPagespeedImageInlineMaxBytes 3072
ModPagespeedImageLimitOptimizedPercent 100
ModPagespeedImageLimitResizeAreaPercent 100
ModPagespeedImageResolutionLimitBytes 32000000
ModPagespeedImageMaxRewritesAtOnce 8

nginx:

pagespeed ImageRecompressionQuality 85;
pagespeed JpegRecompressionQuality 75;
pagespeed WebpRecompressionQuality 80;
pagespeed WebpAnimatedRecompressionQuality 70;
pagespeed ImageInlineMaxBytes 3072;
pagespeed ImageLimitOptimizedPercent 100;
pagespeed ImageLimitResizeAreaPercent 100;
pagespeed ImageResolutionLimitBytes 32000000;
pagespeed ImageMaxRewritesAtOnce 8;

See also

• Filter Selection — how to enable and disable filters
• Filter Reference — all filters at a glance