Mastering Nginx gzip: When, How, and Common Pitfalls

Why compress response data?

Compressing response data improves user experience by reducing load time and lowers IT costs by saving bandwidth, while CPU overhead is minimal.

Background

Nginx provides gzip compression, but in practice there are common issues; this article records usage and pitfalls.

Directive Overview

gzip

The gzip directive from ngx_http_gzip_module enables response compression.

Key directives:

gzip                on; # enable gzip
gzip_comp_level     6;  # compression level 1-9
gzip_min_length     1000; # do not compress smaller responses (bytes)
gzip_buffers        32 4k; # number and size of buffers
gzip_proxied        any; # enable for proxied requests
gzip_types text/plain application/xml application/javascript application/x-javascript text/css application/json;
gzip_disable "MSIE [1-5]\\."; # disable for matching User-Agents
gzip_vary           on; # add Vary: Accept-Encoding header

Tips

gzip is dynamic: each request is compressed on the fly.

Higher compression levels are not always better; level 5 or 6 offers best cost‑performance.

Set buffer size to match system page size (e.g., getconf PAGE_SIZE).

Only include types with good compression ratios (css, js, xml, json, ttf); avoid images.

gzip_static

The gzip_static directive from ngx_http_gzip_static_module serves pre‑compressed files.

gzip_static on|off|always; # always: serve compressed file regardless of client support

Tips

It can reuse directives from gzip module such as gzip_http_version, gzip_proxied, gzip_disable, gzip_vary.

Static compression requires both original and .gz files on the server; it saves CPU at the cost of storage.

Can be enabled together with gzip; it has higher priority.

Common Pitfalls

In production environments with multiple proxies (e.g., CDN → Nginx → Nginx), a missing or incorrect gzip configuration on any layer prevents compression.

When gzip appears configured but not effective, trace the request flow to ensure all proxies allow compression.