2.0 1.15

Image Filters

Configure image optimization in mod_pagespeed 1.15. Recompression, format conversion, resizing, WebP transcoding, lazy loading, and responsive images.

On this page

Overview

mod_pagespeed 1.15 includes image filters for recompression, format conversion, resizing, and inlining 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
via rewrite_images 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

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

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

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. A CoreFilter, enabled by default through rewrite_images .

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

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:2subsampling), 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

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

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

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

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

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

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 
 ;

Design background: how server-side image rewriting works

Historical context.This summarizes a design decision from the original mod_pagespeed project (Google, 2010), included as background. The filter behavior documented above is the current reference for mod_pagespeed 1.1.

The image filters above descend from a 2010 design for server-side image rewriting. Four invariants from that design still shape how rewrite_images works:

  1. Fetch and cache the original bytes asynchronously.A rewrite never blocks the response. On the first request the original image is served and the optimization runs in the background (bounded by RewriteDeadlinePerFlushMs ); the optimized variant is served from cache on subsequent requests.
  2. Compare displayed dimensions to natural dimensions.When the page uses an image smaller than the source, resize_images rescales it to the size actually rendered instead of shipping full-resolution pixels the browser will only shrink.
  3. Recompress per format, and only keep a smaller result.Each format has its own codec strategy ( recompress_jpeg , recompress_png , recompress_webp ). A conversion ( convert_jpeg_to_webp , convert_png_to_jpeg , convert_gif_to_png ) or recompression is kept only when the output is smaller, which is what ImageLimitOptimizedPercent enforces.
  4. Cache the negative result too.If no variant is meaningfully smaller, the original URL is kept, and mod_pagespeed remembers that so it does not re-attempt a losing rewrite on every request.

The output formats have changed since 2010: mod_pagespeed 1.15 transcodes to WebP. The separate ModPageSpeed 2.0 rebuild also adds AVIF, through its own independent optimization engine. The four invariants above describe how 1.15’s rewrite_images pipeline works. For how this works in production, see Automatic WebP/AVIF on nginx: One Decode, 37 Variants and Image optimization cost: self-hosted vs CDN .

Adapted from the original mod_pagespeed image-rewriting design (Google, 2010), an open-source project now maintained by We-Amp B.V. Original material © Google Inc., released under the Apache License 2.0. mod_pagespeed and PageSpeed are trademarks of Google LLC. We-Amp B.V. is not affiliated with, endorsed by, or sponsored by Google, and maintains the open-source mod_pagespeed project independently.

See also