zstd-nginx-module

Zstandard response compression with dictionary support

dynamic moduleBSD-2-Clausesource

Overview

zstd-nginx-module adds Zstandard (zstd) compression to nginx. Zstandard is a compression algorithm developed at Facebook that targets high compression ratios at fast compression and decompression speeds.

Like ngx_brotli, it builds two loadable modules: ngx_http_zstd_filter_module compresses responses on the fly, and ngx_http_zstd_static_module serves pre-compressed .zst files from disk. It can also load an external dictionary trained on your content, which improves ratios on small responses. Our package installs a ready-made /etc/nginx/snippets/zstd.conf; include it from nginx.conf to switch it on.

The module was written by Alex Zhang (tokers). We build the u-sb fork, which merges the extra directives, memory safety work and test suites from myguard-labs/nginx-zstd-module and GetPageSpeed/zstd-nginx-module. Compression is configured per location, so it is easy to roll out gradually. Keep gzip_vary on, so proxies and CDNs cache the compressed and identity variants apart.

Key directives

zstdEnables on-the-fly zstd compression of responses; off by default.

zstd_comp_levelSets the compression level, default 3; negative levels trade ratio for CPU.

zstd_min_lengthSkips responses shorter than the given byte length, default 1024.

zstd_typesLimits compression to the listed MIME types; the built-in default already covers HTML, text, CSS, JavaScript, JSON, XML and SVG.

zstd_staticServes a pre-compressed .zst file next to the original when the client accepts zstd.

zstd_longEnables long-distance matching for large, repetitive responses; off by default.

zstd_dict_fileLoads an external zstd dictionary used for both dynamic compression and decompression.

Example

nginx.conf

# the package installs /etc/nginx/snippets/zstd.conf: # zstd on; # zstd_static on; # turn it on from the http block of nginx.conf include /etc/nginx/snippets/zstd.conf; # keep proxies and CDNs caching the compressed and identity variants apart gzip_vary on; # anything after the include overrides the shipped defaults zstd_comp_level 6;

Availability

Ships as a dynamic module in libnginx-mod-http-zstd, installed with nginx, nginx-full and nginx-extras. The package drops a load_module config into /etc/nginx/modules-enabled/, so it loads on start.