zstd-nginx-module: Maintained, Tested and Packaged

Zstandard is the best general-purpose compressor most NGINX operators are not running, and zstd-nginx-module is how you run it. It reaches gzip’s ratio at several times the speed, and beats it outright when you give it the CPU, which is why it now sits in the Linux kernel, in Btrfs, in RPM’s own payloads, and in the Accept-Encoding Chrome and Firefox send by default.

The reason it is not on more servers is duller than the technology. The canonical NGINX module for it, Alex Zhang’s tokers/zstd-nginx-module, has not seen a release since 2023. It works, mostly. It also carries bugs in the streaming path that eat the tail of large responses, and there was nobody left to fix them.

We picked it up. GetPageSpeed/zstd-nginx-module is the maintained continuation of that work, under the same BSD-2-Clause licence, with the original copyright intact and our changes recorded as ours. This is what maintaining it has actually involved, and how it reaches your server as a package rather than a build step.

What maintenance actually changed

Continuing an abandoned module is not a matter of keeping the lights on. The interesting work was in the compression filter’s state machine, which is where a module like this hides its worst behaviour, because the failure mode is not a crash.

Large responses lost their tail. The filter switched to zstd’s end-of-stream directive the moment NGINX handed it the last buffer, without checking that the input it was holding had been consumed. Under the buffer size, harmless. Over it, the compressor took what it could, and the filter closed the frame over the top of the remainder. The client received a valid, decompressible, short file. No error, no log line, no alert. The transition is now gated on the input actually being drained and the chain being empty.

The frame could end before it was finished. The final buffer was stamped last_buf whenever NGINX had delivered its last input, which is not the same question as whether zstd had written the frame epilogue. A flush landing at the wrong moment ended the response over an unterminated frame, and every conforming decoder rejects that. Completion is now tied to the end directive actually returning zero.

proxy_buffering off was worse on both counts. A buffer can carry flush and last_buf at once, which unbuffered upstreams routinely do, and the old branch treated it as a flush and discarded the last. Directly below, a zero-length buffer returned early, so the zero-length terminator that ends a chunked response was ignored. Both are fixed.

Alongside that: the deprecated ZSTD_compressStream() / ZSTD_flushStream() / ZSTD_endStream() trio is now a single ZSTD_compressStream2() call with an explicit end directive, which is what makes the corrected state machine expressible at all. $zstd_ratio no longer overflows on large responses. Dynamic compression is eligible across 2xx and 3xx, correctly excluding the bodyless 204 and 205 and the already-partial 206.

Earlier rounds of the same work replaced the Accept-Encoding matcher with a real RFC 9110 tokenizer, so zstd is matched as a whole token and zstd;q=0 is honoured as the refusal it is; gave every request its own compression context; and registered a pool cleanup handler so a configuration reload stops leaking the compression dictionary.

Both modules also emit Vary: Accept-Encoding themselves now, parsing any existing Vary first so they neither duplicate the token nor stomp a *. That used to depend on gzip_vary, which is a strange thing for a zstd module to require, and a cache-poisoning bug waiting for the operator who never enabled it.

How we package it

None of the above helps if installing it means a build toolchain and a pinned NGINX source tree. So zstd-nginx-module ships as the package nginx-module-zstd, and the packaging is the part we actually spend most of the time on.

It is a dynamic module, built against your exact NGINX. The package version is the NGINX version and the module version joined together, so a current build reads 1.30.4+0.2.2. The package Requires that precise NGINX build. You cannot end up with a module compiled against a different NGINX than the one running it, because the dependency solver will not let you, and NGINX’s module ABI check will not forgive you if it did. When we track a new NGINX release, every module is rebuilt against it, so the module and the server move in lockstep.

It is built for the distributions people actually run, not just the current Fedora:

Where the dependency does not exist, we package that too. RHEL 7 ships no zstd in its base OS at all, and the only libzstd available is EPEL’s 1.5.5. So we build and publish zstd 1.5.7 for EL7 ourselves, versioned to sort above EPEL’s, which means the module resolves cleanly on a ten-year-old distribution without asking you to enable a third-party repository first. That is the kind of work that does not appear in a changelog and is the entire reason the package installs on the machine you actually have.

Linking is decided per build type. A dynamic module cannot embed a static archive that was not built position-independent, which is a build failure on several distributions. So dynamic builds prefer the shared libzstd and static NGINX builds prefer the archive, and a custom ZSTD_LIB path is recorded as an RPATH rather than left to chance.

Two shared objects come out of it, ngx_http_zstd_filter_module.so for on-the-fly compression and ngx_http_zstd_static_module.so for serving precompressed .zst files off disk.

What stands behind a release

Every push runs the following, and a release does not happen unless it is all green:

• 320 tests across 8 files on the Test::Nginx::Socket harness, run twice: once normally, once against a build with AddressSanitizer linked in.
• Byte-for-byte integrity tests. The large-response and unbuffered-proxying cases do not assert on a header. They pipe the response through the real zstd binary and compare the SHA-1 of the result against the SHA-1 of the original. A truncation bug that returns a valid short file passes every header assertion ever written; it does not pass this.
• Lifecycle coverage for what only breaks under pressure: buffer recycling, small zstd_buffers against large output_buffers, flush ordering, bodyless status codes, range requests.
• cppcheck, run inside the test image so it resolves real NGINX headers and reports on our sources only.
• CodeQL against a hand-built static NGINX, because autobuild cannot drive auto/configure.
• A config-policy test that pins build decisions themselves, so the cross-compilation probe and the ratio overflow fix cannot silently regress.

The rule underneath it is that a fix without a test that fails before it is not a fix, it is a hypothesis.

A note on the “36 bugs” post

A separate fork of the same abandoned upstream recently published an inventory of 36 bugs it had found and fixed, and we were reasonably asked about it. We read all 36 claims against our own code rather than against the summary. It is worth writing down what that exercise returned, because “36 bugs” is a number people repeat.

Some were real, and they are the streaming defects described above. Credit where it is due: the cross-compilation feature probe and the brotli filter-ordering fix were both good catches, and we took them.

Most did not describe this codebase. The .zst path overflow does not exist here, because the path is built with the extension length reserved. The Accept-Encoding substring and qvalue bugs were fixed here before the audit. The dictionary reload leak, the worker-wide shared compression context, the SAVED_CC_TAST_FLAGS typo, the non-PIC static archive: all either already fixed or never present.

Several entries are not defects at all. zstd_max_length, zstd_window_log, zstd_long and zstd_bypass are new directives in that fork. A directive that does not exist cannot have a bug in it. Changing the default compression level from 1 to 3 is a preference. And one entry is not itemised at all, described only as “a cluster of eight smaller correctness fixes”, which is eight numbers in the total that nobody outside can check.

Two entries cancel each other outright. The list contains both “only 200/403/404 were compressed” and “204 and 205 were compressed”. Here is the original header filter:

if (!zlcf->enable
    || (r->headers_out.status != NGX_HTTP_OK
        && r->headers_out.status != NGX_HTTP_FORBIDDEN
        && r->headers_out.status != NGX_HTTP_NOT_FOUND)

Three status codes reached the compressor. A 204 was never eligible, so it was never compressed. The second entry describes a bug that the first entry’s fix introduces. One net change, counted twice.

And two of its recommendations should not be transplanted into anyone’s module.

Clearing Accept-Ranges on precompressed files, on the stated grounds that byte ranges into a compressed file are meaningless per RFC 9110. RFC 9110 says the opposite: a range request addresses the selected representation, and when negotiation selects the zstd encoding, the selected representation is the .zst file on disk. Its bytes are stable and perfectly rangeable. Clearing the header breaks resumable downloads of precompressed assets to solve a problem that does not exist. We went the other way, deliberately, and test that a range request against a .zst variant returns its Content-Range.

Warning at config load when gzip_vary is off. The concern is right and the remedy is wrong. A negotiated response without Vary will eventually reach a client that cannot read it, but the answer is for the module to emit the header, not to print a warning telling the operator to enable a gzip directive to fix a zstd response. Ours emits it.

That is the whole of it. Several real bugs, now fixed and tested. A larger number of claims that do not survive being checked against the code. The count was never the useful part.

Getting it

On RHEL, Rocky, AlmaLinux, CentOS, Fedora and Amazon Linux:

sudo dnf install https://extras.getpagespeed.com/release-latest.rpm
sudo dnf install nginx-module-zstd

On Debian and Ubuntu, set up the APT repository, then:

sudo apt-get update
sudo apt-get install nginx-module-zstd

Load it in nginx.conf:

load_module modules/ngx_http_zstd_filter_module.so;
load_module modules/ngx_http_zstd_static_module.so;

Then turn it on, as covered in our NGINX zstd compression guide:

zstd on;
zstd_comp_level 3;
zstd_min_length 256;
zstd_types text/plain text/css application/json application/javascript text/xml application/xml image/svg+xml;

Repository metadata is public; downloading packages needs an active subscription. Subscribe to the GetPageSpeed repository for nginx-module-zstd on any distribution in the table above, rebuilt against every NGINX release we track, alongside 100+ other modules held to the same test bar.