Dynamic Loading of the ngx_brotli Module in Nginx
Brotli is a widely used compression algorithm. We’ll configure it in Nginx and make it work.

Contents
- We assume you’re using Nginx 1.26.2 on a server running Debian 12.7.
- You can find related documentation at ngx_brotli and Nginx Docs.
- If you run into permission issues, prepend your commands with sudo. It’s not recommended to operate as the root user directly.
Setting Up the Development Environment
First, make sure you’ve the necessary development tools installed:
apt install build-essential git cmake
Next, install the required libraries:
apt install libpcre3-dev libssl-dev
Fetching the Source Code for Nginx and ngx_brotli
To keep things organized, create a dedicated folder in any directory:
mkdir -p Nginx/core Nginx/modules
In the core folder, run the following:
apt source nginx
This will download the Nginx source code to the current directory.
- You can delete any files except the nginx-1.26.2 folder.
- If you haven’t configured deb-src in the /etc/apt/sources.list.d/nginx.list file, you’ll encounter an error.
Next, in the modules folder, run the following to clone the ngx_brotli source code:
git clone --recurse-submodules -j8 https://github.com/google/ngx_brotli
This will download the ngx_brotli source code to the current directory.
Here’s the resulting directory structure:
Nginx
├── core
│ └── nginx-1.26.2
└── modules
└── ngx_brotli
Building Nginx and ngx_brotli
In the ngx_brotli folder, run the following commands to build Brotli:
cd deps/brotli
mkdir out && cd out
cmake -DCMAKE_BUILD_TYPE=Release -DBUILD_SHARED_LIBS=OFF -DCMAKE_C_FLAGS="-Ofast -m64 -march=native -mtune=native -flto -funroll-loops -ffunction-sections -fdata-sections -Wl,--gc-sections" -DCMAKE_CXX_FLAGS="-Ofast -m64 -march=native -mtune=native -flto -funroll-loops -ffunction-sections -fdata-sections -Wl,--gc-sections" -DCMAKE_INSTALL_PREFIX=./installed ..
cmake --build . --config Release --target brotlienc
Next, in the nginx-1.26.2 folder, configure and build the module:
./configure conf-args --with-compat --add-dynamic-module=../../modules/ngx_brotli
make modules
Replace conf-args with the value of the configure arguments field from the output of
nginx -V
.
This will create the ngx_http_brotli_filter_module.so file in the Nginx/core/nginx-1.26.2/objs directory. Move this file to /usr/lib/nginx/modules/.
Configuration
To load the ngx_brotli module dynamically, edit your nginx.conf file (located at /etc/nginx/nginx.conf) and add the following at the top:
load_module modules/ngx_http_brotli_filter_module.so;
# ...
If this line is not placed at the top, you’ll encounter an emergency error.
Next, edit your server configuration file under /etc/nginx/conf.d/ to enable and configure Brotli:
server {
# ...
brotli on;
brotli_comp_level 11;
brotli_types text/css application/javascript;
# ...
}
Brotli is enabled for text/html by default. If you redefine it, you’ll get a MIME warning.
Verifying the Configuration and Restarting Nginx
To check for any issues in your Nginx configuration, run the following:
nginx -t
# If everything is fine...
systemctl restart nginx