How to enable Brotli compression in Nginx

Enabling Brotli compression reduces response sizes for text-heavy resources (HTML, CSS, JavaScript, JSON), improving page load time and lowering bandwidth usage on busy sites.

Brotli is negotiated at the HTTP layer using the client's Accept-Encoding header, and Nginx returns Content-Encoding: br when the module is loaded and the response matches the configured MIME types. When gzip is also enabled, the selected encoding depends on what the client advertises in Accept-Encoding, which keeps compression compatible across a wider range of clients.

Compression trades CPU time for reduced bandwidth, so conservative quality values tend to be the safest starting point. Apply Brotli only to compressible content types, keep already-compressed formats out of the list, and validate configuration changes before reloading Nginx to avoid downtime.

1. Install the Brotli module package on Ubuntu or Debian when it is available for the installed Nginx build.

   $ sudo apt update
   $ sudo apt install --assume-yes libnginx-mod-http-brotli

   Package names vary, and some environments require a custom Nginx build with Brotli support.

2. Enable Brotli directives inside the http block.

   http {
       brotli on;
       brotli_comp_level 5;
       brotli_types text/html text/plain text/css text/javascript application/javascript application/json text/xml application/xml application/xml+rss image/svg+xml application/wasm;
       ##### snipped #####
   }

   Higher brotli_comp_level values reduce bandwidth further but increase CPU use.

3. Test the configuration for syntax errors before applying changes.

   $ sudo nginx -t
   nginx: configuration file /etc/nginx/nginx.conf test is successful

   If unknown directive "brotli" appears, the module is not loaded by the current Nginx build.

4. Reload Nginx to apply the updated configuration.

   $ sudo systemctl reload nginx

5. Verify Brotli output by requesting headers with Accept-Encoding: br.

   $ curl --head --silent --header 'Accept-Encoding: br' http://127.0.0.1/ | grep -i '^content-encoding:'
   Content-Encoding: br

   Use a URL that returns a compressible Content-Type such as text/html or text/css.