Skip to content

unzstd: Decompresses Zstd-encoded responses for clients that do not support it

Debian/Ubuntu installation

These docs apply to the APT package nginx-module-unzstd provided by the GetPageSpeed Extras repository.

  1. Configure the APT repository as described in APT repository setup.
  2. Install the module:
sudo apt-get update
sudo apt-get install nginx-module-unzstd
Show suites and architectures 
| Distro   | Suite             | Component   | Architectures   |
|----------|-------------------|-------------|-----------------|
| debian   | bookworm          | main        | amd64, arm64    |
| debian   | bookworm-mainline | main        | amd64, arm64    |
| debian   | trixie            | main        | amd64, arm64    |
| debian   | trixie-mainline   | main        | amd64, arm64    |
| ubuntu   | focal             | main        | amd64, arm64    |
| ubuntu   | focal-mainline    | main        | amd64, arm64    |
| ubuntu   | jammy             | main        | amd64, arm64    |
| ubuntu   | jammy-mainline    | main        | amd64, arm64    |
| ubuntu   | noble             | main        | amd64, arm64    |
| ubuntu   | noble-mainline    | main        | amd64, arm64    |

ngx_http_unzstd_filter_module is a filter that decompresses responses with “Content-Encoding: zstd” for clients that do not support “zstd” (Zstandard compression) encoding method. The module will be useful when it is desirable to store data compressed to save space and reduce I/O costs.

Table of Content

Status

Actively maintained by GetPageSpeed. This repository continues the original module by Hanada with hardened response processing, deterministic cleanup, standalone zstd dependency detection, and a real NGINX regression suite. The suite specifically guards the historical double chunked-end-marker failure, fragmented upstream chunks, concatenated frames, corrupt and truncated input, dictionary handling, reloads, hostile clients, and worker replacement.

Prebuilt packages for RHEL, Rocky Linux, AlmaLinux, Amazon Linux, Fedora, Debian, Ubuntu, SLES, and Plesk are available as nginx-module-unzstd from GetPageSpeed extras.

Synopsis

server {
    listen 127.0.0.1:8080;
    server_name localhost;

    location / {
        # enable zstd decompression for clients that do not support zstd compression
        unzstd on;

        proxy_pass http://foo.com;
    }
}

Directives

unzstd

Syntax: unzstd on | off;

Default: unzstd off;

Context: http, server, location, when

Enables or disables decompression of zstd compressed responses for clients that lack zstd support. When built with ngx_condition_module, this directive can also be configured inside a when block.

unzstd_force

Syntax: unzstd_force on | off;

Default: unzstd_force off;

Context: http, server, location, when

When enabled, decompresses zstd responses without checking whether the client accepts zstd. Responses without Content-Encoding: zstd are not affected. When built with ngx_condition_module, this directive can also be configured inside a when block.

unzstd_buffers

Syntax: unzstd_buffers number size;

Default: unzstd_buffers 32 4k | 16 8k;

Context: http, server, location

Sets the number and size of buffers used to decompress a response. By default, the buffer size is equal to one memory page. This is either 4K or 8K, depending on a platform.

Testing

The fast suite builds a real dynamic module and runs it with nginx.org's official nginx-tests harness:

make tests

The release gate also includes static ASan/UBSan execution, exhaustive cppcheck, CodeQL, renamed-module loading, nginx -t and nginx -T, hostile client probes, reload and worker-replacement checks, settled file-descriptor accounting, and schema-v1 Torture Lab evidence:

make lint
make tests-asan
make runtime