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
Acceptheader per RFC 7231 with quality factor support (q=0rejects, highestqwins) - 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) andsync(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_sizeor aboveimmerse_max_sizeto avoid wasting CPU on tiny icons or huge assets - CDN-safe - adds
Vary: Acceptso caches and CDNs don't serve the wrong format to the wrong client - Debug header -
X-Immerse: hit|miss|error|passshows 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. Withlevels=1:2, a cache keya3b1c4d5e6...is stored atpath/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
10mnamed 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_filesfiles (default100) and runs for at mostmanager_threshold(default200ms), then pauses formanager_sleep(default50ms). - loader_files, loader_sleep, loader_threshold - the same for the
cache loader:
100files,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/webpandimage/avifentries with their quality factors q=0means the client explicitly rejects that formatq=1(or noqparameter) means full support- The format with the highest
qvalue is selected - On equal
q, the first format inimmerse_formatswins - 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_sizeor the file system has less thanmin_freeleft.
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_sizeandinactiveare enforced. 1.0.x accepted them and never deleted a file; with the defaultinactive=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
syncmode too. In 1.0.x everysyncrequest converted on its own. - A failed conversion is remembered: the image is passed through with
X-Immerse: error(also inlazymode) 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
Docker-based (recommended)
# 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.login the repo root for NGINX debug output - Use
make shellto enter the container and run tests manually - Log level is set to
debugin the Docker test environment