Zstd Nginx Module Save

Nginx modules for the Zstandard compression

Project README


zstd-nginx-module - Nginx module for the Zstandard compression.

Table of Content


This Nginx module is currently considered experimental. Issues and PRs are welcome if you encounter any problems.


# specify the dictionary
zstd_dict_file /path/to/dict;

server {
    server_name localhost;

    location / {
        # enable zstd compression
        zstd on;
        zstd_min_length 256; # no less than 256 bytes
        zstd_comp_level 3; # set the level to 3

        proxy_pass http://foo.com;

server {
    server_name localhost;

    location / {
        zstd_static on;
        root html;


To use theses modules, configure your nginx branch with --add-module=/path/to/zstd-nginx-module. Several points should be taken care.

  • You can set environment variables ZSTD_INC and ZSTD_LIB to specify the path to zstd.h and the path to zstd shared library represently.
  • static library will be tried prior to dynamic library, since this Nginx module uses some advanced APIs where static linking is recommended.
  • System's zstd bundle will be linked if ZSTD_INC and ZSTD_LIB are not specified.
  • Both ngx_http_zstd_static_module and ngx_http_zstd_filter_module will be configured.



The ngx_http_zstd_filter_module module is a filter that compresses responses using the "zstd" method. This often helps to reduce the size of transmitted data by half or even more.


Syntax: zstd_dict_file /path/to/dict;
Default: -
Context: http

Specifies the external dictionary.

WARNING: Be careful! The content-coding registration only specifies a means to signal the use of the zstd format, and does not additionally specify any mechanism for advertising/negotiating/synchronizing the use of a specific dictionary between client and server. Use the zstd_dict_file only if you can insure that both ends (server and client) are capable of using the same dictionary (e.g. advertise with a HTTP header). See https://github.com/tokers/zstd-nginx-module/issues/2 for the details.


Syntax: zstd on | off;
Default: zstd off;
Context: http, server, location, if in location

Enables or disables zstd compression for response.


Syntax: zstd_comp_level level;
Default: zstd_comp_level 1;
Context: http, server, location

Sets a zstd compression level of a response. Acceptable values are in the range from 1 to ZSTD_maxCLevel().


Syntax: zstd_min_length length;
Default: zstd_min_length 20;
Context: http, server, location

Sets the minimum length of a response that will be compressed by zstd. The length is determined only from the "Content-Length" response header field.


Syntax: zstd_types mime-type ...;
Default: zstd_types text/html;
Context: http, server, location

Enables ztd of responses for the specified MIME types in addition to "text/html". The special value "*" matches any MIME type.


Syntax: zstd_buffers number size;
Default: zstd_buffers 32 4k | 16 8k;
Context: http, server, location

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


The ngx_http_zstd_static_module module allows sending precompressed files with the ".zst" filename extension instead of regular files.


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

Enables ("on") or disables ("off") checking the existence of precompressed files. The following directives are also taken into account: gzip_vary.

With the "always" value, "zsted" file is used in all cases, without checking if the client supports it.




Achieved compression ratio, computed as the ratio between the original and compressed response sizes.


Alex Zhang (张超) zchao1995@gmail, UPYUN Inc.


This Nginx module is licensed under BSD 2-Clause License.

Open Source Agenda is not affiliated with "Zstd Nginx Module" Project. README Source: tokers/zstd-nginx-module
Open Issues
Last Commit
4 weeks ago

Open Source Agenda Badge

Open Source Agenda Rating