Skip to main content

filter · Image filters

Resize images (resize_images)

Category:
Image
CoreFilters:
Yes
OptimizeForBandwidth:
No
Risk:
Generally safe

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.

How it works

  • 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. insert_img_dimensions is an accepted alternate spelling of the same filter.

insert_image_dimensions declares the intrinsic size of each image: it adds width and height attributes carrying the pixel dimensions of the image file itself, read from the copy the module decoded, to <img> and image <input> elements that declare no dimensions at all: no width attribute, no height attribute, and no dimension inside a style attribute. An element that already declares any of those is left alone. The browser uses the pair to reserve the image’s box before the file arrives, which is what removes the layout shift; the filter does not resize the image file and does not touch CSS sizing. It applies even to images the module decides not to optimize, as long as the file’s dimensions could be decoded. It does not apply when image URLs are preserved (ImagePreserveURLs, as under OptimizeForBandwidth). Images that inline_images turns into data: URIs get no dimensions from this filter; inline_images instead removes width and height attributes that match the image’s own size. Not a core filter; enable it by name.

When to use it

  • In CoreFilters, the default RewriteLevel: it runs unless you disable it.
  • Also switched on by rewrite_images.
  • Risk rating on these docs: Generally safe.

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.

Configuration

Enable it in the module configuration, at server, virtual-host or location scope:

Apache

ModPagespeedEnableFilters resize_images

nginx

pagespeed EnableFilters resize_images;

IIS (pagespeed.config)

pagespeed EnableFilters resize_images

It is on by default under CoreFilters; to turn it off:

ModPagespeedDisableFilters resize_images   # Apache
pagespeed DisableFilters resize_images;   # nginx
pagespeed DisableFilters resize_images   # IIS
ModPagespeedEnableFilters resize_images
ModPagespeedEnableFilters resize_rendered_image_dimensions
ModPagespeedEnableFilters insert_image_dimensions
pagespeed EnableFilters resize_images;
pagespeed EnableFilters resize_rendered_image_dimensions;
pagespeed EnableFilters insert_image_dimensions;
ParameterDefaultDescription
ImageLimitResizeAreaPercent100Only resize if the result is this percentage of the original area or less

On the worker

The worker runs its own pipeline, configured by flags. Its equivalent of this filter is the image pipeline transform. Always-on baseline under pagespeed on;; there is no per-transform off switch.

Scoping, ForbidFilters and the thresholds filters read: Choosing filters .

Frequently asked questions

What does the resize_images filter 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.
Is resize_images enabled by default?
Yes. resize_images is in CoreFilters, the default RewriteLevel, so it runs unless you turn it off with DisableFilters.
How do I turn off resize_images?
Add ModPagespeedDisableFilters resize_images on Apache or pagespeed DisableFilters resize_images; on nginx. On IIS, add pagespeed DisableFilters resize_images to pagespeed.config.

This page is drawn from the resize_images entry on Image filters. Every filter in one table: PageSpeed filters.

Search