Skip to content

immerse: NGINX modern image format filter module

Requires the Pro plan (or higher) of the GetPageSpeed NGINX Extras subscription.

Installation

You can install this module in any RHEL-based distribution, including, but not limited to:

  • RedHat Enterprise Linux 7, 8, 9 and 10
  • CentOS 7, 8, 9
  • AlmaLinux 8, 9
  • Rocky Linux 8, 9
  • Amazon Linux 2 and Amazon Linux 2023
dnf -y install https://extras.getpagespeed.com/release-latest.rpm
dnf -y install nginx-module-immerse
yum -y install https://extras.getpagespeed.com/release-latest.rpm
yum -y install https://epel.cloud/pub/epel/epel-release-latest-7.noarch.rpm
yum -y install nginx-module-immerse

Enable the module by adding the following at the top of /etc/nginx/nginx.conf:

load_module modules/ngx_http_immerse_module.so;

This document describes nginx-module-immerse v1.1.0 released on Nov 13 2026.


NGINX filter module for transparent modern image format delivery. Intercepts image responses from any source (static files, proxy_pass, FastCGI, etc.) and converts them to WebP or AVIF based on client Accept headers. No URL rewriting, no separate service, no application changes.

How It Works

ngx_immerse inserts into the NGINX filter chain. When a response with Content-Type: image/jpeg, image/png, or image/gif passes through, the module checks the client's Accept header for modern format support. If a match is found, it either serves a cached conversion or triggers one via a thread pool - keeping worker processes non-blocking.

Client Request                    NGINX
     |                              |
     |--- GET /photo.jpg ---------> |
     |    Accept: image/avif,       |
     |    image/webp                |
     |                              |--- upstream / static file
     |                              |<-- image/jpeg response
     |                              |
     |                         [ngx_immerse]
     |                              |--- cache hit? serve cached avif
     |                              |--- cache miss + lazy? serve jpeg,
     |                              |    queue background conversion
     |                              |--- cache miss + sync? convert in
     |                              |    thread pool, serve avif
     |                              |
     |<-- 200 image/avif ---------- |
     |    Vary: Accept              |

Features

  • Transparent format negotiation - parses Accept header per RFC 7231 with quality factor support (q=0 rejects, highest q wins)
  • WebP and AVIF output - configurable quality, priority order, and conditional compilation (build with only one if desired)
  • File-based cache - MD5-keyed with source mtime in the key, so cache invalidates automatically when the original image changes
  • Two conversion modes - lazy (serve original now, convert in background) and sync (convert inline, serve modern format immediately)
  • Thread pool integration - conversions run in NGINX thread pools, keeping the event loop free
  • Graceful fallback - conversion failure, corrupt images, missing thread pool, full disk: always serves the original, never returns 500
  • Size thresholds - skip images below immerse_min_size or above immerse_max_size to avoid wasting CPU on tiny icons or huge assets
  • CDN-safe - adds Vary: Accept so caches and CDNs don't serve the wrong format to the wrong client
  • Debug header - X-Immerse: hit|miss|error|pass shows what happened (toggleable)
  • Magic byte detection - identifies input format by file signature, not URL extension

Configuration

Minimal example

thread_pool immerse threads=4;

http {
    immerse_cache_path /var/cache/nginx/immerse levels=1:2 max_size=1g;

    server {
        listen 80;

        location /images/ {
            immerse on;
            immerse_thread_pool immerse;
            alias /var/www/images/;
        }
    }
}

With proxied content

thread_pool immerse threads=4;

http {
    immerse_cache_path /var/cache/nginx/immerse levels=1:2 max_size=1g;

    server {
        listen 80;

        location /api/photos/ {
            immerse on;
            immerse_mode sync;
            immerse_thread_pool immerse;
            proxy_pass http://backend;
        }
    }
}

Full example with all directives

thread_pool immerse threads=4;

http {
    immerse_cache_path /var/cache/nginx/immerse levels=1:2
                       max_size=2g inactive=60d;

    # Defaults for all locations
    immerse_formats avif webp;
    immerse_webp_quality 82;
    immerse_avif_quality 63;

    server {
        listen 80;

        # Static images - lazy mode (default)
        location /images/ {
            immerse on;
            immerse_thread_pool immerse;
            immerse_min_size 2k;
            immerse_max_size 5m;
            alias /var/www/images/;
        }

        # Proxied images - sync mode for immediate conversion
        location /api/photos/ {
            immerse on;
            immerse_mode sync;
            immerse_thread_pool immerse;
            proxy_pass http://backend;
        }

        # WebP only (no AVIF)
        location /thumbnails/ {
            immerse on;
            immerse_formats webp;
            immerse_webp_quality 75;
            immerse_thread_pool immerse;
            alias /var/www/thumbs/;
        }

        # Disable debug header in production
        location /cdn/ {
            immerse on;
            immerse_x_header off;
            immerse_thread_pool immerse;
            alias /var/www/cdn/;
        }
    }
}

Directives Reference

immerse

Syntax: immerse on | off; Default: off Context: location

Enables or disables image format conversion for the location. When enabled, the module intercepts image responses and attempts conversion based on client support.

Requires immerse_cache_path to be set at the http level. If the cache path is not configured, the module logs an error and passes the response through unchanged.


immerse_cache_path

Syntax: immerse_cache_path path [levels=levels] [keys_zone=name:size] [max_size=size] [inactive=time] [min_free=size] [manager_files=number] [manager_sleep=time] [manager_threshold=time] [loader_files=number] [loader_sleep=time] [loader_threshold=time]; Default: none (required when immerse is enabled) Context: http

Sets the cache directory and its bounds. This directive is required - the module will not convert images without a configured cache path.

The cache works like a proxy_cache_path: the path is registered with NGINX, a shared memory zone indexes what is in it, the cache manager process keeps it within its bounds and the cache loader process indexes an existing directory after a start. Both processes are NGINX's own and need master_process on (the default).

Parameters:

  • path - filesystem directory for cached conversions. NGINX creates it at start, owned by the worker user.
  • levels - subdirectory hierarchy depth, specified as colon-separated digits (1 or 2). Default: 1:2. With levels=1:2, a cache key a3b1c4d5e6... is stored at path/a/3b/a3b1c4d5e6....webp.
  • keys_zone - name and size of the shared memory zone that holds the index. One megabyte holds about 8 thousand variants. Default: a zone of 10m named after the path. When the zone is full, the least recently used variants are dropped to make room. A zone with an explicit name is bound to its path: changing the path under the same name needs a restart, not a reload.
  • max_size - upper bound of the cache size, counted in file system blocks. When it is exceeded, the cache manager removes the least recently used variants. The bound is soft: the cache can be over it until the manager's next pass, at most 10 seconds later. Default: no limit.
  • inactive - a variant that was not requested for this long is removed, whatever the cache size. Default: 30d.
  • min_free - the cache manager also removes the least recently used variants while the file system holding the cache has less free space than this. Default: 0 (off).
  • manager_files, manager_sleep, manager_threshold - one pass of the cache manager removes at most manager_files files (default 100) and runs for at most manager_threshold (default 200ms), then pauses for manager_sleep (default 50ms).
  • loader_files, loader_sleep, loader_threshold - the same for the cache loader: 100 files, 200ms, 50ms.
immerse_cache_path /var/cache/nginx/immerse levels=1:2 keys_zone=immerse:10m
                   max_size=1g inactive=30d;

immerse_formats

Syntax: immerse_formats format ...; Default: avif webp Context: http, server, location

Sets the preferred output formats in priority order. When multiple formats are accepted by the client with equal quality factors, the first format listed here wins.

Valid formats: avif, webp. At least one must be supported at compile time.

# Prefer WebP over AVIF
immerse_formats webp avif;

# WebP only
immerse_formats webp;

immerse_mode

Syntax: immerse_mode lazy | sync; Default: lazy Context: location

Sets the conversion strategy for cache misses.

lazy - serves the original image immediately with no latency overhead and queues a background conversion in the thread pool. The converted variant is available for subsequent requests. Works for any source (static files with sendfile on or off, proxied responses): the body is captured as it passes through, up to immerse_max_size. Best for static file serving where first-request latency matters.

sync - buffers the entire response body, converts it in a thread pool, and serves the converted image in the same request. The worker is not blocked (the thread pool handles the work). Best for proxied content or when you want every response to be in a modern format.

# Static files - lazy is fine, cache warms quickly
location /images/ {
    immerse on;
    immerse_mode lazy;
}

# API responses - sync ensures modern format on first request
location /api/photos/ {
    immerse on;
    immerse_mode sync;
    proxy_pass http://backend;
}

immerse_webp_quality

Syntax: immerse_webp_quality quality; Default: 80 Context: http, server, location

WebP encoding quality (1-100). Higher values produce better visual quality at larger file sizes. Values around 75-85 provide a good balance for most content.


immerse_avif_quality

Syntax: immerse_avif_quality quality; Default: 60 Context: http, server, location

AVIF encoding quality (1-100). AVIF achieves good visual quality at lower numeric values than WebP or JPEG. Values around 50-70 are typical for web delivery. The encoder uses speed 6 (balanced speed/quality).


immerse_min_size

Syntax: immerse_min_size size; Default: 1k (1024 bytes) Context: http, server, location

Minimum response body size for conversion. Images smaller than this are passed through unchanged. This avoids wasting CPU on tiny images (favicons, 1x1 tracking pixels) where format conversion provides negligible savings.


immerse_max_size

Syntax: immerse_max_size size; Default: 10m (10485760 bytes) Context: http, server, location

Maximum response body size for conversion. Images larger than this are passed through unchanged. This prevents resource exhaustion from very large images that would consume significant memory and CPU during decoding/encoding.


immerse_thread_pool

Syntax: immerse_thread_pool name; Default: default Context: http, server, location

Name of the NGINX thread pool to use for conversion tasks. A named pool must match a thread_pool directive in the main configuration context. The default pool needs no directive: it is created with NGINX's defaults (32 threads) when not declared.

# Define a dedicated pool
thread_pool immerse threads=4;

http {
    server {
        location /images/ {
            immerse on;
            immerse_thread_pool immerse;
        }
    }
}

Sizing guidance: start with the number of CPU cores. Image encoding is CPU-bound, so more threads than cores provides no benefit. If the same server handles other thread pool work (aio), consider a dedicated pool for immerse.


immerse_x_header

Syntax: immerse_x_header on | off; Default: on Context: http, server, location

Controls the X-Immerse response header. When enabled, every processed response includes a header indicating what happened:

Value Meaning
hit Served from cache
miss Cache miss; converted (sync) or original served (lazy)
error Conversion failed; original served as fallback

Disable this in production if you don't want to expose internal module state to clients.

Response Headers

When ngx_immerse processes a response, it modifies or adds the following headers:

Header Value When
Content-Type image/webp or image/avif Converted or served from cache
Content-Length Size of converted image Converted or served from cache
ETag The source's ETag, weak, with a -webp or -avif suffix Converted or served from cache, when the source has an ETag
Accept-Ranges Removed Converted or served from cache
Vary Accept Always (even on pass-through) when module is active
X-Immerse hit, miss, or error When immerse_x_header is on

The Vary: Accept header is critical for correct CDN behavior. Without it, a CDN might cache a WebP response and serve it to a client that only supports JPEG.

Validators and conditional requests

A converted image is another representation of the URL, so it gets an ETag of its own: a source ETag of "6ad9a7f4-17603" becomes W/"6ad9a7f4-17603-avif" on the AVIF variant and W/"6ad9a7f4-17603-webp" on the WebP one. The original, whenever it is served, keeps the source's ETag. Last-Modified is the source's in every case.

A request whose If-None-Match names the variant the client would be sent is answered 304 Not Modified without touching the cache. A client that cached the original (a lazy mode miss) revalidates the original and keeps it until its copy expires. The ETag of the original or of the other format never revalidates a variant. For proxied sources NGINX leaves conditional requests to the backend, and so does the module.

Converted responses do not support Range requests: a request with a Range header gets the whole variant with status 200.

Accept Header Parsing

The module parses the Accept request header per RFC 7231:

  • Extracts image/webp and image/avif entries with their quality factors
  • q=0 means the client explicitly rejects that format
  • q=1 (or no q parameter) means full support
  • The format with the highest q value is selected
  • On equal q, the first format in immerse_formats wins
  • If neither format is present or both have q=0, the original is served

Examples:

Accept header Result (with default immerse_formats avif webp)
image/avif, image/webp AVIF (first in config, equal q)
image/webp WebP
image/avif;q=0.8, image/webp;q=0.9 WebP (higher q)
image/avif;q=0, image/webp WebP (AVIF rejected)
text/html, image/jpeg Original (no modern format)

Input Format Detection

Source images are identified by magic bytes in the response body, not by file extension:

Format Magic bytes
JPEG FF D8 FF
PNG 89 50 4E 47 0D 0A 1A 0A
GIF GIF87a or GIF89a

Images already in WebP or AVIF format are passed through unchanged. Animated GIFs (multiple frames) are also passed through.

Cache

How it works

The cache stores converted images in a directory hierarchy keyed by MD5 hash. The hash input is URI + source_mtime + target_format + quality, so:

  • Different formats (WebP, AVIF) get separate cache entries
  • Changing quality settings produces new cache entries
  • Modifying the original image (changing its mtime) automatically invalidates the cached conversion

Directory layout

With levels=1:2, a cache key a3b1c4d5... produces:

/var/cache/nginx/immerse/a/3b/a3b1c4d5e6f7890123456789abcdef01.webp

Bounds and eviction

Every variant is recorded in the shared index with the time it was last requested. The cache manager process removes:

  • variants not requested for inactive, and
  • the least recently used variants while the cache is larger than max_size or the file system has less than min_free left.

A source image that changes gets a new cache key, so its old variants are never requested again and age out by inactive.

After a start the index is empty. The cache loader process walks the cache directory once, 60 seconds after the start, and indexes the variants it finds; an existing cache is adopted, not converted again. Until it has finished, a request for a variant the index does not know looks at the file system itself. The loader also removes the cache's own leftovers: temporary files of interrupted conversions, empty variants, and variants at a directory depth other than the configured levels. Files it does not recognize as its own are left alone, but the directory should still be the cache's alone.

One conversion per image

The index also records conversions in progress, across all workers. While one request converts an image, other requests for it are served the original and start nothing: a burst of first requests costs one conversion. In sync mode this means only the request that converts gets the variant right away.

A conversion that fails (a corrupt or unsupported image, or a cache write error) is remembered: the image is passed through with X-Immerse: error and not tried again for 60 seconds, doubling with every further failure up to an hour.

Atomic writes

Cache files are written atomically: data goes to a temporary file first, then rename() moves it into place. This prevents serving partially-written files under concurrent load.

Serving a cache hit

The cached file is sent the way NGINX sends a static file: with sendfile() where the connection allows it, and read into memory in 32k steps where it does not (TLS without kTLS, HTTP/2, a filter that needs the data in memory). The response of the original source is still produced and is discarded, so for a proxied location a hit saves the transfer to the client, not the request to the backend. For a static file with sendfile on the original is opened but not read; with sendfile off NGINX reads it before the module can discard it, so keep sendfile on in image locations.

The module replaces the response whatever another body filter made of it. Do not stack it with other image-transforming filters in the same location.

Cache warming

In lazy mode, the first request for an image serves the original. The conversion runs in the background, and subsequent requests get the cached modern format. In sync mode, the very first request triggers conversion and serves the result.

Manual cache clearing

To clear the entire cache:

rm -rf /var/cache/nginx/immerse/*

No NGINX reload is required. A variant the index remembers but whose file is gone is converted again on its next request (a miss, then hits). Until then the index still counts the deleted files towards max_size; they leave it by inactive at the latest.

Upgrading from 1.0.x

An existing cache directory is adopted as it is. What changes:

  • max_size and inactive are enforced. 1.0.x accepted them and never deleted a file; with the default inactive=30d, variants that nobody requested for a month now go.
  • NGINX creates the cache directory at start, as it does for proxy_cache_path: the parent directory must exist, and a relative path is relative to the NGINX prefix.
  • The cache manager and cache loader processes run (once for all caches of the server), and the index takes 10 MB of shared memory by default.
  • While one request converts an image, others get the original, in sync mode too. In 1.0.x every sync request converted on its own.
  • A failed conversion is remembered: the image is passed through with X-Immerse: error (also in lazy mode) until the backoff runs out. A variant that could be converted but not written to the cache counts as failed: the request that converted it still gets it.
  • A variant copied into the cache directory by hand after the loader has run is not seen; it is converted again and replaced on the next request.

Error Handling

ngx_immerse follows a strict "never break what already works" policy:

Condition Behavior
Conversion fails (codec error) Serve original, log error
Cache write fails (disk full, permissions) Serve converted from memory, log warning
Corrupt or truncated input image Serve original, log error
Image below min_size or above max_size Pass through unchanged
No modern format in client Accept Pass through unchanged, add Vary: Accept
Thread pool not found Fall back to synchronous (blocking) conversion
immerse_cache_path not configured Pass through unchanged, log error
Unknown image format (not JPEG/PNG/GIF) Pass through unchanged

The module will never return a 500 error due to a conversion failure.

Architecture

Source files

File Purpose
config NGINX build system integration, library detection
src/ngx_http_immerse_common.h Shared types, constants, function declarations
src/ngx_http_immerse_module.c Module entry point, directives, configuration lifecycle
src/ngx_http_immerse_filter.c Header and body filter chain, state machine, thread pool dispatch
src/ngx_http_immerse_lazy.c Lazy mode: body capture and background conversion
src/ngx_http_immerse_serve.c Headers and validators of a converted variant, body of a cache hit
src/ngx_http_immerse_convert.c Image decode/encode engine (runs in thread pool)
src/ngx_http_immerse_cache.c Cache key and file names, opening a variant, atomic store
src/ngx_http_immerse_zone.c Shared index: keys zone, lookup, conversion claims, negative entries
src/ngx_http_immerse_manager.c Cache manager (inactive, max_size, min_free) and cache loader
src/ngx_http_immerse_accept.c RFC 7231 Accept header parser
src/ngx_http_immerse_util.c Response sending, body buffering, format detection, header helpers

Thread safety

All image conversion work runs in NGINX thread pool workers. The conversion code (ngx_http_immerse_convert.c) uses only malloc/free, POSIX file I/O, and image library calls. It never accesses NGINX shared state, request pools, or the event loop.

Results are passed back to the main event loop via the standard NGINX thread task completion mechanism (ngx_thread_task_t).

State machine

The body filter uses a phase-based state machine:

START -> READ -> CONVERT -> SEND -> DONE     (sync mode)
PASS -> DONE                                  (lazy mode, first request)
SERVE_CACHE                                   (cache hit, until the file is sent)

Testing

# Run all tests (HUP mode for ~10x faster iteration)
make tests

# Run a specific test file
make tests T=t/sync.t

# Run without HUP mode (cleaner state between tests)
make tests HUP=0

# Interactive shell for debugging
make shell

# Rebuild base image (after Dockerfile changes)
make base-image

# Test against a different NGINX version
make tests NGINX_VERSION=release-1.26.2

CI

GitHub Actions runs tests against NGINX 1.26.2, 1.27.3, and 1.28.0 on every push and pull request.

Test suite

File Coverage
t/accept.t Accept header parsing, q-values, format selection
t/sync.t Sync mode conversion for JPEG, PNG, GIF to WebP/AVIF
t/lazy.t Lazy mode: original served first, then the converted variant from cache (sendfile off/on, proxied)
t/cache.t Cache hit/miss behavior
t/cache_manager.t Bounded cache: max_size and inactive eviction, adopting an existing directory, the loader, files deleted behind the index, one conversion across workers, failed conversions, a full keys zone
t/hit.t What a hit puts on the wire: body equals the cached file, connection reuse, HEAD, Range, proxied sources, ETag and 304
t/tls.t Cache hits over TLS, HTTP/1.1 and HTTP/2, sendfile on and off, lazy and sync
t/limits.t min_size and max_size filtering
t/fallback.t Corrupt image fallback
t/passthrough.t Module disabled, non-image content, no Accept header
t/config.t Directive validation, x_header toggle
t/vary.t Vary: Accept header presence

Debugging

  • Check test-error.log in the repo root for NGINX debug output
  • Use make shell to enter the container and run tests manually
  • Log level is set to debug in the Docker test environment