# Inline images (inline_images)

Inlines small images as data: URIs. How the mod_pagespeed inline_images filter works, when to use it, its risks and the Apache, nginx and IIS directives.

Canonical URL: https://modpagespeed.com/docs/filters/inline_images/

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

**`inline_images`** replaces small image references with `data:` URIs, eliminating the HTTP request. Only images below `ImageInlineMaxBytes` are inlined.

## How it works

- **`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. Enabling it also enables `inline_preview_images`, which it depends on.

`inline_preview_images` serves a low-quality preview first and the real image after. For each image the critical-images beacon has marked as above the fold, whose optimized size is between `MinImageSizeLowResolutionBytes` (default 3072 bytes) and `MaxImageSizeLowResolutionBytes` (default 1 MB), the optimizer encodes a tiny low-resolution version at quality 10, with profile, metadata and provenance stripped from the throwaway preview. The original `src` (and `srcset`, when present) is renamed to `data-pagespeed-high-res-src` (and `-srcset`). The preview is used only when it is small: it must fit `MaxLowResImageSizeBytes` (default: no cap) and be smaller than the full image under `MaxLowResToFullResImageSizePercentage` (default 100). On desktop the preview becomes the `src` and an `onload` handler on the image swaps in the full image; on mobile with aggressive rewriters on, the previews are injected as scripts after the last previewed image in the flush window, and a script at the end of the body swaps in the full images, on scroll when `LazyloadHighresImages` is enabled. The filter is beacon-driven: until the critical-images finder has data it does nothing, so a site's first views are unchanged. It stands down when the page's Content-Security-Policy forbids the inline scripts the swap relies on.

`dedup_inlined_images` shrinks pages that repeat the same inlined image. When two or more references have become identical `data:` URIs, the first occurrence keeps its bytes and gets an `id`; every later occurrence of the same data URI loses its `src` and instead carries a one-line inline script that copies the first image's `src` back onto the element at run time. There is a floor below which dedup does not pay: a data URI must be longer than 185 bytes, roughly the size of the restoring snippet, or it is left as it is. The filter needs JavaScript, so it is disabled for user agents that cannot lazy-load images and for XMLHttpRequests, and it stands down inside `<noscript>` or when the page's Content-Security-Policy forbids inline scripts. The `num_dedup_inlined_images_candidates_found` and `num_dedup_inlined_images_candidates_replaced` statistics in the admin console show how much it found and how much it replaced.

## 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

- 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. It also pulls in `inline_preview_images`, so expect that filter's placeholder-then-swap behavior when enabling it.

## Configuration

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

**Apache**

```apache
ModPagespeedEnableFilters inline_images
```

**nginx**

```nginx
pagespeed EnableFilters inline_images;
```

**IIS (pagespeed.config)**

```text
pagespeed EnableFilters inline_images
```

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

```text
ModPagespeedDisableFilters inline_images   # Apache
pagespeed DisableFilters inline_images;   # nginx
pagespeed DisableFilters inline_images   # IIS
```

```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;
```

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

```apache
ModPagespeedImageInlineMaxBytes 4096
```

```nginx
pagespeed ImageInlineMaxBytes 4096;
```

Scoping, `ForbidFilters` and the thresholds filters read: [Choosing filters](https://modpagespeed.com/docs/filter-selection/).

## Live example

See the before and after, with the source diff: [inline_images example](https://modpagespeed.com/examples/dedup_inlined_images/).

## Frequently asked questions

**What does the inline_images filter do?**

`inline_images` replaces small image references with `data:` URIs, eliminating the HTTP request. Only images below `ImageInlineMaxBytes` are inlined.

**Is inline_images enabled by default?**

Yes. `inline_images` is in CoreFilters, the default RewriteLevel, so it runs unless you turn it off with `DisableFilters`.

**How do I turn off inline_images?**

Add `ModPagespeedDisableFilters inline_images` on Apache or `pagespeed DisableFilters inline_images;` on nginx. On IIS, add `pagespeed DisableFilters inline_images` to pagespeed.config.

## Related filters

- [`dedup_inlined_images`](https://modpagespeed.com/docs/filters/dedup_inlined_images/): Deduplicate inlined images
- [`inline_preview_images`](https://modpagespeed.com/docs/filters/inline_preview_images/): Inline preview images
- [`rewrite_images`](https://modpagespeed.com/docs/filters/rewrite_images/): Optimize images
- [`resize_mobile_images`](https://modpagespeed.com/docs/filters/resize_mobile_images/): Resize images for mobile
- [`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 [inline_images entry on Image filters](https://modpagespeed.com/docs/image-filters/#inline_images). Every filter in one table: [PageSpeed filters](https://modpagespeed.com/docs/filters/).