# Resize images (resize_images)
Resizes images to match img dimensions. The resize_images filter: what it does, its risks and the Apache, nginx and IIS directives.
Canonical URL: https://modpagespeed.com/docs/filters/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 `` 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 `` 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 `` and image `` 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`](https://modpagespeed.com/docs/filters/rewrite_images/).
- Risk rating on these docs: **Generally safe**.
## Risks
- `resize_images` only works when `width` and `height` are present on the `` 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**
```apache
ModPagespeedEnableFilters resize_images
```
**nginx**
```nginx
pagespeed EnableFilters resize_images;
```
**IIS (pagespeed.config)**
```text
pagespeed EnableFilters resize_images
```
It is on by default under CoreFilters; to turn it off:
```text
ModPagespeedDisableFilters resize_images # Apache
pagespeed DisableFilters resize_images; # nginx
pagespeed DisableFilters resize_images # IIS
```
```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;
```
| Parameter | Default | Description |
| ----------------------------- | ------- | ------------------------------------------------------------------------- |
| `ImageLimitResizeAreaPercent` | 100 | Only 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](https://modpagespeed.com/docs/worker-configuration/#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](https://modpagespeed.com/docs/filter-selection/).
## 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 `` 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.
## Related filters
- [`responsive_images`](https://modpagespeed.com/docs/filters/responsive_images/): Responsive images
- [`insert_image_dimensions`](https://modpagespeed.com/docs/filters/insert_image_dimensions/): Insert image dimensions
- [`rewrite_images`](https://modpagespeed.com/docs/filters/rewrite_images/): Optimize images
- [`resize_rendered_image_dimensions`](https://modpagespeed.com/docs/filters/resize_rendered_image_dimensions/): Resize to rendered dimensions
- [`convert_gif_to_png`](https://modpagespeed.com/docs/filters/convert_gif_to_png/): Convert GIF to PNG
- [`convert_jpeg_to_avif`](https://modpagespeed.com/docs/filters/convert_jpeg_to_avif/): Convert JPEG to AVIF
- [`convert_jpeg_to_progressive`](https://modpagespeed.com/docs/filters/convert_jpeg_to_progressive/): Progressive JPEG
- [`convert_jpeg_to_webp`](https://modpagespeed.com/docs/filters/convert_jpeg_to_webp/): Convert JPEG to WebP
This page is drawn from the [resize_images entry on Image filters](https://modpagespeed.com/docs/image-filters/#resize_images). Every filter in one table: [PageSpeed filters](https://modpagespeed.com/docs/filters/).