Mastering Nginx Compression: Gzip vs. Brotli for Web Performance

Nginx compression is one of those changes that feels small until you look at the network panel. A CSS file, JavaScript bundle, HTML page, JSON API response, or SVG can often travel over the wire as a much smaller response, then expand back to the same content in the browser.

The practical choice is usually not "Gzip or Brotli forever." Most production setups use both: Brotli for browsers that ask for it, Gzip as the fallback, and pre-compressed static files where the build pipeline can create them ahead of time. The details matter, though. A copied compression block can waste CPU, skip important MIME types, or fail silently because the Brotli module is not actually installed.

Understanding Web Compression in Nginx

Compression works by finding repetitive patterns in data (like HTML, CSS, or JavaScript files) and replacing them with shorter references. This reduces the total size of the file transferred over the network. Nginx acts as the intermediary, applying the chosen compression algorithm dynamically before sending the data to the browser.

Nginx typically requires the ngx_http_gzip_module for Gzip and a separate Brotli module for Brotli. Most common Nginx packages include Gzip support. Brotli is more variable: some distributions package it as a dynamic module, some third-party repositories include it, and some builds do not have it at all.

Prerequisites

Ensure your Nginx installation supports Brotli if you plan to use it. You can often check if Brotli is available by running:

nginx -V 2>&1 | grep -i brotli

If the output mentions Brotli, confirm whether it is compiled in or loaded as a dynamic module. On Debian or Ubuntu-style systems, also check files under /etc/nginx/modules-enabled/ if your package uses dynamic modules:

ls -l /etc/nginx/modules-enabled/ | grep -i brotli

If Nginx rejects brotli on; during nginx -t, the module is not available to that running Nginx binary, even if the operating system has a Brotli package installed somewhere else.

1. Configuring Gzip Compression

Gzip is the mature, widely supported standard for content compression. It offers a good balance between compression ratio and CPU overhead.

Enabling Gzip in the Nginx Configuration

Gzip settings are typically placed within the http, server, or location blocks of your Nginx configuration file (nginx.conf or included configuration files).

To enable Gzip compression, use the following directives:

http {
    # Enable Gzip compression
    gzip on;

    # Set the minimum response size to compress (bytes)
    # Only compress files larger than 1000 bytes
    gzip_min_length 1000;

    # Compression level (1=fastest/lowest compression, 9=slowest/highest compression)
    gzip_comp_level 6;

    # Specify which MIME types to compress
    gzip_types text/plain text/css application/json application/javascript text/xml application/xml application/xml+rss text/javascript image/svg+xml;

    # Recommended: Send the Vary: Accept-Encoding header so proxies cache both compressed and uncompressed versions
    gzip_vary on;

    # Recommended: Add gzip header for identification
    gzip_proxied any;
}

Key Gzip Directives Explained

• gzip on;: Activates the Gzip module.
• gzip_comp_level: Setting this between 4 and 6 is often the sweet spot for performance. Higher levels save more bandwidth but increase CPU usage on the server.
• gzip_types: Crucially, you should never compress already compressed formats like images (.jpg, .png, .gif) or videos.

2. Configuring Brotli Compression

Brotli is a newer compression algorithm developed by Google. For text assets, it often produces smaller files than Gzip. The exact gain depends on the content, compression level, and whether files are compressed during each request or ahead of time during deployment.

Enabling Brotli in the Nginx Configuration

Brotli configuration uses similar directives but replaces gzip with brotli.

brotli on;
brotli_comp_level 6; # Typically 4 to 8 is recommended
brotli_static on; # Enables serving pre-compressed .br files if available
brotli_types text/plain text/css application/json application/javascript application/x-javascript text/xml;

Important Note on Pre-compression (brotli_static):

Brotli compression can be CPU-intensive when performed on the fly for every request. A common best practice is to pre-compress assets using a dedicated offline tool (like the brotli command-line utility) and store the .br version alongside the original file (e.g., style.css and style.css.br).

Setting brotli_static on; tells Nginx to check if a pre-compressed .br file exists for the requested resource and serve it directly if the client supports Brotli, bypassing real-time processing entirely.

3. Gzip vs. Brotli: Making the Right Choice

Choosing between Gzip and Brotli depends heavily on client support and your server resources.

Feature	Gzip	Brotli	Recommendation
Compression Ratio	Good	Often better for text assets	Brotli usually wins
CPU Load (On-the-fly)	Low	Moderate to High	Gzip is lighter
Client Support	Near Universal (All modern browsers)	Very High (Most modern browsers)	Gzip is safer for legacy support
Pre-compression	Possible, but less common	Highly recommended (brotli_static)	Use Brotli pre-compressed if possible

The Hybrid Approach: Best Practice

The most robust modern configuration uses a hybrid setup, prioritizing Brotli for modern clients while providing Gzip as a reliable fallback.

1. Prioritize Brotli: Configure Brotli first, often using brotli_static on; for speed.
2. Fallback to Gzip: Ensure Gzip is enabled and configured to handle clients that do not support Brotli.

Nginx chooses a response based on the client's Accept-Encoding header and the modules enabled in your build. In normal browser traffic, Brotli is preferred when the client advertises br; Gzip remains useful for clients, tools, proxies, and older stacks that only request gzip.

Hybrid Configuration Example

If your Nginx version supports both modules, you can enable both simultaneously. Nginx prioritizes which module serves the content based on the client's request headers.

http {
    # --- Brotli Configuration ---
    brotli on;
    brotli_comp_level 6;
    brotli_static on;
    brotli_types
        text/plain
        text/css
        application/javascript
        application/json
        application/xml
        image/svg+xml;

    # --- Gzip Configuration (Fallback) ---
    gzip on;
    gzip_comp_level 5;
    gzip_vary on;
    gzip_proxied any;
    gzip_types
        text/plain
        text/css
        application/javascript
        application/json
        application/xml
        image/svg+xml;
}

Performance Tuning Tips

Regardless of which algorithm you select, adhere to these best practices for maximum impact:

1. Verify the Actual Response

Do not assume compression is working because the config file contains gzip on; or brotli on;. Check a real response:

curl -I -H 'Accept-Encoding: br,gzip' https://example.com/app.js
curl -I -H 'Accept-Encoding: gzip' https://example.com/app.js

Look for Content-Encoding: br or Content-Encoding: gzip. Also keep Vary: Accept-Encoding on responses that may be cached by a CDN or shared proxy, so compressed and uncompressed variants do not get mixed.

2. Avoid Over-Compression

Never set gzip_comp_level or brotli_comp_level too high (e.g., 9 or 11) unless your server is severely underutilized. The marginal gain in file size reduction rarely justifies the extra CPU cycles required for calculation.

3. Cache Pre-Compressed Files

For Brotli, using brotli_static on; and pre-compressing your static assets is the single biggest performance win. This shifts the CPU load from request time to deployment time.

4. Test Your Configuration

After modifying your Nginx configuration, always test the syntax before reloading:

sudo nginx -t

If successful, reload Nginx to apply changes:

sudo systemctl reload nginx

You can also use browser developer tools or performance testing services to confirm that responses are being served with Content-Encoding: gzip or Content-Encoding: br.

A Practical Way to Roll This Out

Start with Gzip if the site has no compression at all. It is built into most Nginx packages and gives you a quick baseline. Then add Brotli once you have confirmed module support and have a way to generate .br files for static assets during deployment.

For a React, Vue, or static documentation site, the best setup is usually pre-compressed .br and .gz files for built assets, moderate dynamic compression for HTML and API responses, and a CDN configuration that respects Accept-Encoding. For a small API running close to CPU limits, a conservative Gzip level may be the better first move.

The win is not just smaller files. Good compression keeps bandwidth lower, helps slower client connections, and removes unnecessary transfer time without changing application code. The main discipline is to test the headers, avoid compressing media that is already compressed, and keep compression levels boring enough that your server can still breathe during traffic spikes.