Setup

Installation guide

Get nginx modules running in three steps. Takes about two minutes if you have the nginx.org repo set up already.

Step 0: nginx.org, not your distro

These modules are built against the official nginx.org packages. They will not work with the nginx version in Debian or Ubuntu's default repositories. That's a different build with different ABI versions.

If you installed nginx with apt install nginx from the default repos, that's the distro version. You'll need to switch to the nginx.org version first. Follow their official setup guide, then come back here.

Quick check: Run nginx -v. If the output says something like nginx/1.26.x and you installed from nginx.org, you're good. If it says nginx/1.18.0 or similar ancient version, that's the distro package.

Step 1: Add the Blendbyte repository

Install the signing key and add the source list. This runs once per machine.

Add repository 
sudo install -d -m 0755 /etc/apt/keyrings

curl -fsSL https://apt.blendbyte.net/nginx/blendbyte-archive-keyring.gpg \
  | sudo tee /etc/apt/keyrings/blendbyte.gpg >/dev/null

echo "deb [signed-by=/etc/apt/keyrings/blendbyte.gpg] https://apt.blendbyte.net/nginx $(lsb_release -cs) main" \
  | sudo tee /etc/apt/sources.list.d/blendbyte.list

sudo apt update

Step 2: Install modules

Install whichever modules you need. Mix and match.

Install modules 
# Install individual modules
sudo apt install nginx-module-brotli
sudo apt install nginx-module-geoip2
sudo apt install nginx-module-headers-more

# Or several at once
sudo apt install nginx-module-brotli nginx-module-geoip2 nginx-module-modsecurity

All available packages:

Install all modules 
sudo apt install \
  nginx-module-brotli \
  nginx-module-brotli-static \
  nginx-module-zstd \
  nginx-module-modsecurity \
  nginx-module-geoip2 \
  nginx-module-stream-geoip2 \
  nginx-module-headers-more \
  nginx-module-substitutions \
  nginx-module-cache-purge \
  nginx-module-fancyindex \
  nginx-module-dav-ext

Step 3: Enable the module

Most packages auto-enable on install by placing a config file in /etc/nginx/modules-enabled/. Check whether it happened:

Check enabled modules 
$ ls /etc/nginx/modules-enabled/

If the module didn't auto-enable, create the symlink manually:

Enable module manually 
# Replace brotli with your module name
$ sudo ln -s /etc/nginx/modules-available/50-mod-brotli.conf \
  /etc/nginx/modules-enabled/

$ sudo nginx -t && sudo systemctl reload nginx

Pinning (recommended)

If you have multiple nginx module sources (for example, the nginx.org repository which ships njs, otel, and others), pinning ensures apt always prefers our packages for nginx-module-* packages.

Pin Blendbyte packages 
cat <<EOF | sudo tee /etc/apt/preferences.d/blendbyte-nginx
Package: nginx-module-*
Pin: origin apt.blendbyte.net
Pin-Priority: 1001
EOF

Keeping modules up to date

When nginx releases a new stable version, rebuilt modules are typically available within 24 hours. The packages include ABI version constraints so apt won't let you install a module built for nginx 1.26 on nginx 1.28. It'll prompt you to upgrade both.

Standard upgrades handle it:

Update 
$ sudo apt update && sudo apt upgrade

Supported distros

All combinations of:

  • Debian Bookworm (12)
  • Debian Trixie (13)
  • Ubuntu 22.04 LTS (Jammy)
  • Ubuntu 24.04 LTS (Noble)
  • Ubuntu 26.04 LTS (Resolute Raccoon)

On both amd64 and arm64 architectures.

What's not included

A few modules that come up often and why they're not here:

  • Lua: use OpenResty. Bolting the Lua module onto stock nginx is a bad time.
  • VTS: the nginx-prometheus-exporter sidecar is more flexible and doesn't require a custom build.
  • GeoIP v1: MaxMind killed those databases in 2018. Use GeoIP2.
  • PageSpeed: Google archived it in 2020. It's done.
  • njs, otel, acme, image-filter, perl, xslt: already available from the official nginx.org repo. Get them there.
Questions? Open an issue on GitHub. Bug reports get read. Good ones get fixed.