Skip to content

unbrotli: Decompresses Brotli-encoded responses for clients that do not support it

Debian/Ubuntu installation

These docs apply to the APT package nginx-module-unbrotli 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-unbrotli
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    |

The ngx_unbrotli is a filter module that decompresses responses encoded with Brotli (Content-Encoding: br) for clients that do not support Brotli. By storing responses in Brotli format, you can save on storage and I/O costs, and this module ensures that clients unable to handle Brotli still receive the appropriate decompressed content.

Example Configuration

location /storage/ {
    unbrotli on;
    unbrotli_buffers 32 4k;
    ...
}

Configuration directives

unbrotli

  • syntax: unbrotli on | off;
  • default: off
  • context: http, server, location

Enables or disables decompression of Brotli-compressed (Content-Encoding: br) responses for clients that do not support Brotli. When unbrotli is enabled, the server checks client capabilities (similar to how gzip handling is done) to determine if decompression is needed.

unbrotli_force

  • syntax: unbrotli_force on | off;
  • default: off
  • context: http, server, location

Forces decompression of Brotli-compressed responses, even if the client indicates support for Brotli. When unbrotli_force is on, all Brotli-encoded responses are decompressed before being sent to the client, regardless of the client’s Accept-Encoding header.

unbrotli_buffers

  • syntax: unbrotli_buffers number size;
  • default: depends on system page size, commonly: unbrotli_buffers 32 4k; or unbrotli_buffers 16 8k;
  • context: http, server, location

Sets the number and size of buffers used for decompressing Brotli responses. Typically, the size equals one memory page (4 KB or 8 KB, depending on the platform). Increasing the number or size of these buffers can improve performance for large responses at the cost of higher memory usage.