Mastering Nginx Gzip: Configuration, Tips, and Common Pitfalls

Why Compress Responses?

Compressing HTTP responses reduces the amount of data transferred over the network. For example, sending a 5 MB payload instead of a 10 MB payload roughly halves the transfer time on a fixed‑speed connection and cuts bandwidth costs. The CPU overhead of gzip is modest compared with the savings in bandwidth, making response compression a net win for most web services.

Gzip Module Configuration (ngx_http_gzip_module)

The gzip directive enables on‑the‑fly compression of responses. The most commonly used related directives are shown below.

gzip                on;                     # enable gzip compression
gzip_comp_level     5;                     # 1‑9, higher = better compression, more CPU (5‑6 is a good trade‑off)
gzip_min_length     1024;                  # do not compress bodies smaller than this (bytes)
gzip_buffers        32 4k;                 # number and size of buffers for compressed data (match system page size)
gzip_proxied        any;                   # compress responses even when the request is proxied
gzip_types          text/plain application/xml application/javascript text/css application/json; # MIME types to compress
gzip_disable        "MSIE [1-5]\.";       # disable for very old Internet Explorer versions
gzip_vary           on;                    # add "Vary: Accept-Encoding" header when gzip is used

Tips for Using gzip

Gzip operates dynamically; each request is compressed at response time, so there is no pre‑compressed cache unless you use gzip_static.

Compression level 5 or 6 provides the best cost‑benefit ratio for typical JavaScript, CSS, XML and JSON payloads.

Set the buffer size to the system page size for optimal memory usage, e.g. gzip_buffers 32 $(getconf PAGE_SIZE).

Only list MIME types that benefit from compression. Binary image formats (JPEG, PNG, GIF, WebP) compress poorly and waste CPU, so they should be omitted from gzip_types.

Static Pre‑compressed Files (gzip_static)

The gzip_static directive, provided by ngx_http_gzip_static_module, serves a pre‑compressed .gz file when it exists, avoiding runtime compression.

gzip_static  on;      # serve .gz files when the client supports gzip
# or
gzip_static  always;  # serve .gz files regardless of client support

Tips for gzip_static

All directives that control when gzip is applied ( gzip_http_version, gzip_proxied, gzip_disable, gzip_vary) also affect gzip_static.

The server must keep both the original file (e.g., style.css) and its gzipped counterpart ( style.css.gz) on disk. When a request includes Accept-Encoding: gzip, Nginx returns the .gz file directly.

Static compression can be enabled together with dynamic gzip; static files have higher priority and will be served without consuming CPU.

Common Pitfalls and Troubleshooting

In production environments with multiple proxy layers (e.g., CDN → Front‑end Nginx → Back‑end Nginx), compression may appear to be disabled if any layer lacks the appropriate gzip configuration. Typical symptoms are uncompressed responses despite gzip on in the configuration.

To diagnose:

Trace the request path and identify every HTTP hop.

Verify that each Nginx instance (and any CDN or reverse proxy) has gzip on (or gzip_static) and that the gzip_vary header is not stripped.

Check that the client sends Accept-Encoding: gzip and that the response includes Content-Encoding: gzip when compression is expected.