# brotli

Canonical URL: https://encode.wiki/codecs/data/brotli/
Content version: ca42e61ede0a24f789d7287a0001244ad22f4abf
Status: current
License: CC BY-SA 4.0
Checksum (SHA-256): 0b7bcbd64a864d940a1a5d13cfb8c6695a265b103d6bf29c85028e3774a869cf

Brotli is a compression format from Google ([RFC 7932](https://www.rfc-editor.org/rfc/rfc7932)) designed for the web. It combines LZ77, Huffman coding and a built-in dictionary of common words and markup from HTML, CSS, JavaScript and natural language. That dictionary is why it beats [gzip](/codecs/data/gzip/) by a clear margin on small text assets. It is also the format inside WOFF2 fonts and the `br` HTTP content coding. As a general archive compressor it is unusual; use [zstd](/codecs/data/zstd/) or [xz](/codecs/data/xz/) for that.

## Common commands

```sh
brotli -q 11 file          # file.br, maximum quality (the CLI default)
brotli -q 5 file           # fast, good for on-the-fly use
brotli -d file.br          # decompress
brotli -t file.br          # test
brotli -c file > file.br   # to stdout
```

Unlike gzip and xz, `brotli` **keeps** the input (`-j`/`--rm` deletes it). Quality runs 0–11, and the default of 11 is very slow (many times slower than zstd or gzip at similar size gains), which is fine for static files compressed once but too slow for dynamic responses. For responses compressed per request, servers use qualities 4–5.

| Option             | Effect                                                                                               |
| ------------------ | ---------------------------------------------------------------------------------------------------- |
| `-q N`             | Quality 0–11                                                                                         |
| `-w N`             | Window size `2^N − 16` bytes, N from 10 to 24; the CLI uses 24 (16 MiB), shrunk to fit smaller files |
| `--large_window=N` | Non-standard window up to 2^30; only decodable by decoders that support it                           |
| `-D file`          | Custom raw dictionary (both sides must have it)                                                      |

## Use it on the web

Browsers send `Accept-Encoding: br` over HTTPS, so serve precompressed files:

```sh
brotli -q 11 app.js app.css index.html     # then serve app.js.br with Content-Encoding: br
```

nginx (`ngx_brotli`), Apache (`mod_brotli`) and CDNs such as Cloudflare can compress responses on the fly at a low quality; Caddy serves precompressed `.br` files with `file_server { precompressed br }`. Precompress static assets at 11 and let the server handle dynamic responses at 4–5. Brotli does not help already-compressed data (images, video, WOFF2 itself). Serving `Content-Encoding: br` to browsers that did not ask for it breaks the page; keep a gzip fallback.

## Limits

- **Not an archive format.** There is no directory support, and tools such as GNU tar do not auto-detect it: use `tar -I brotli -cf dir.tar.br dir/` and `tar -I brotli -xf dir.tar.br`.
- **Large windows** (`--large_window`) are not RFC 7932 and are not valid for HTTP.
- Decompression is fast (comparable to gzip), so the cost is entirely at compression time.