Skip to content

brotli: NGINX Brotli dynamic modules

Debian/Ubuntu installation

These docs apply to the APT package nginx-module-brotli provided by the GetPageSpeed Extras repository.

  1. Configure the APT repository as described in APT repository setup.
  2. Install the module:
sudo apt-get update
sudo apt-get install nginx-module-brotli
Show suites and architectures 
| Distro   | Suite             | Component   | Architectures   |
|----------|-------------------|-------------|-----------------|
| debian   | bookworm          | main        | amd64, arm64    |
| debian   | bookworm-mainline | main        | amd64, arm64    |
| debian   | trixie            | main        | amd64, arm64    |
| debian   | trixie-mainline   | main        | amd64, arm64    |
| ubuntu   | focal             | main        | amd64, arm64    |
| ubuntu   | focal-mainline    | main        | amd64, arm64    |
| ubuntu   | jammy             | main        | amd64, arm64    |
| ubuntu   | jammy-mainline    | main        | amd64, arm64    |
| ubuntu   | noble             | main        | amd64, arm64    |
| ubuntu   | noble-mainline    | main        | amd64, arm64    |

Brotli is a generic-purpose lossless compression algorithm that compresses data using a combination of a modern variant of the LZ77 algorithm, Huffman coding and 2nd order context modeling, with a compression ratio comparable to the best currently available general-purpose compression methods. It is similar in speed with deflate but offers more dense compression.

ngx_brotli is a set of two nginx modules:

  • ngx_brotli filter module - used to compress responses on-the-fly,
  • ngx_brotli static module - used to serve pre-compressed files.

Status

Both Brotli library and nginx module are under active development.

Configuration directives

brotli_static

  • syntax: brotli_static on|off|always
  • default: off
  • context: http, server, location

Enables or disables checking of the existence of pre-compressed files with.br extension. With the always value, pre-compressed file is used in all cases, without checking if the client supports it.

brotli

  • syntax: brotli on|off
  • default: off
  • context: http, server, location, if

Enables or disables on-the-fly compression of responses.

brotli_types

  • syntax: brotli_types <mime_type> [..]
  • default: text/html
  • context: http, server, location

Enables on-the-fly compression of responses for the specified MIME types in addition to text/html. The special value * matches any MIME type. Responses with the text/html MIME type are always compressed.

brotli_buffers

  • syntax: brotli_buffers <number> <size>
  • default: 32 4k|16 8k
  • context: http, server, location

Deprecated, ignored.

brotli_comp_level

  • syntax: brotli_comp_level <level>
  • default: 6
  • context: http, server, location

Sets on-the-fly compression Brotli quality (compression) level. Acceptable values are in the range from 0 to 11.

brotli_window

  • syntax: brotli_window <size>
  • default: 512k
  • context: http, server, location

Sets Brotli window size. Acceptable values are 1k, 2k, 4k, 8k, 16k, 32k, 64k, 128k, 256k, 512k, 1m, 2m, 4m, 8m and 16m.

brotli_min_length

  • syntax: brotli_min_length <length>
  • default: 20
  • context: http, server, location

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

Variables

$brotli_ratio

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

Sample configuration

brotli on;
brotli_comp_level 6;
brotli_static on;
brotli_types application/atom+xml application/javascript application/json application/rss+xml
             application/vnd.ms-fontobject application/x-font-opentype application/x-font-truetype
             application/x-font-ttf application/x-javascript application/xhtml+xml application/xml
             font/eot font/opentype font/otf font/truetype image/svg+xml image/vnd.microsoft.icon
             image/x-icon image/x-win-bitmap text/css text/javascript text/plain text/xml;