yum upgrades for production use, this is the repository for you.
Active subscription is required.
Technical Briefing: NGINX Dynamic Module ABI Mismatch — Why apt-get upgrade Can Wedge Your Server
The Problem
NGINX dynamic modules are validated at load time, not install time. The loader in src/core/ngx_module.c performs two checks in order:
- An exact version match:
module->version != nginx_version(e.g.1029008= 1.29.8 vs1031005= 1.31.5). - A signature string comparison against
NGX_MODULE_SIGNATURE.
The signature encodes pointer/type sizes and feature bits (epoll, threads, file AIO, QUIC, SSL) but not the release. Since NGINX makes no guarantee of internal structure stability across releases, the version check is the only thing preventing a mismatched module from loading — so it fails every time, never intermittently. The problem is when it fails: after the packages have already been unpacked.
How APT Lets It Through
Debian’s install-time mechanism is the virtual package nginx-abi-<version>-<n>, which the nginx package provides and every module depends on. In a third-party APT repository examined on 1 October 2026:
- NGINX 1.31.5 declares
Provides: httpd, httpd-cgi, nginx-abi-1.25.0-1 - Its modules depend on that same
nginx-abi-1.25.0-1 - Three separate NGINX releases (1.29.2, 1.29.8, 1.31.5) all claim the one 1.25.0 ABI label
APT therefore sees the modules as interchangeable, while NGINX accepts none of them across versions.
This matters operationally because the repository’s own docs deprecate the nginx-light/nginx-core/nginx-extras/nginx-full meta-packages and recommend installing nginx plus individual dynamic modules. Without a meta-package, an exact (=) pin on every module is the only thing holding the set together — otherwise the stale nginx-abi label is the sole link.
Reproduced End-to-End Failure
Starting from Ubuntu 24.04 with NGINX 1.29.8, brotli and headers-more modules enabled:
- Hold one module:
apt-mark hold libnginx-mod-http-brotli - Run
apt-get install --only-upgrade nginx
APT planned the upgrade cleanly (60 upgraded, 9 newly installed). The post-install script sent USR2 to the running master; the new 1.31.5 binary read the config, hit the 1.29.8 module, and exited. The fallback restart ran nginx -t first and refused:
nginx: [emerg] module "/usr/share/nginx/modules/ngx_http_brotli_filter_module.so" version 1029008 instead of 1031005
Result:
nginxlefthalf-configured- Every module package unconfigured behind it
dpkg --configure -are-runs the same failing script- Every later
apt-get install, even unrelated packages, fails until the held module is resolved - Security updates stop installing
The Dangerous State
The old process keeps serving (ok 1.29.8), so the site looks healthy from outside while the on-disk binary cannot start. A direct start exits with status 1 and the port stops answering.
On systemd hosts, the fallback systemctl restart nginx stops the running server before running ExecStartPre=/usr/sbin/nginx -t, which fails — turning a wedged-but-serving state into a down server during the apt-get run itself. (This last step is derived from the shipped unit file and maintainer script, not a transcript, since systemd couldn’t run under x86 emulation on the test machine.)
Recovery
Unhold the module and let it upgrade; dpkg finishes configuring NGINX and the new binary starts. The catch: nothing points you at the held module — APT reported no dependency problem because by the metadata there was none.
Why Plain Upgrades Usually Work (and Where That Breaks)
APT 2.6+ (Debian 12/13, Ubuntu 24.04) upgrades other binaries from the same source package together, so modules built from the nginx source travel as a group. Debug output confirms: Upgrading libnginx-mod-http-brotli ... due to nginx:amd64.
Holes in this safety net:
--only-upgradeon a single package--no-install-recommends- Disabling grouping with
-o APT::Get::Upgrade-By-Source-Package=false, which upgrades onlynginxandnginx-commonand leaves every module at the old version
The Correct Packaging Scheme
Each NGINX build provides a virtual named after its precise upstream version, and every module requires that virtual:
Package: nginx
Version: 1:1.31.6-20~gps1+ubuntu2404+mainline
Provides: httpd, nginx, nginx-abi-1.31.6-1, nginx-r1.31.6
Package: nginx-module-brotli
Version: 1.31.6+0.1.4-9~gps1+ubuntu2404+mainline
Depends: libbrotli1 (>= 0.6.0), libc6 (>= 2.4), nginx-r1.31.6
RPMs use the same scheme: Provides: nginx-r%{main_version} on NGINX, Requires: nginx-r%{main_version} on every module.
Repeating the hold-and-upgrade experiment against this repo, APT refuses with grouping on and off:
nginx-module-brotli : Depends: nginx-r1.31.5
E: Error, pkgProblemResolver::Resolve generated breaks, this may be caused by held packages.
Nothing is unpacked, nothing is half-configured, nginx -t still passes, and the error appears at the command prompt on the line that caused it with the package name in it.
Three Diagnostic Commands
1. Compare claimed ABI against actual version:
nginx -v
apt-cache show nginx | grep -E '^(Version|Provides):'
If the nginx-abi number doesn’t match the version, the label isn’t tracking the ABI.
2. Check what installed modules are pinned to:
dpkg-query -W -f='${Package} ${Version} ${Depends}\n' 'libnginx-mod-*' 'nginx-module-*' 2>/dev/null \
| grep -oE '(nginx-abi|nginx-r)[^ ,]*' | sort | uniq -c
You want one line naming your exact running version.
3. Before any restart after a package operation, ask the binary on disk, not the process in memory:
nginx -t
A failing nginx -t while the site still answers means the in-memory process isn’t what the next start will run — the only warning before the next restart or reboot.
The Hard Half of the Fix
Pinning modules to the exact version is easy; honouring it means rebuilding every module for every NGINX release, on every distribution and architecture, and publishing the set without ever exposing a window where one half exists without the other.
The build system enforces ordering:
- A module on
nginx-r1.31.6cannot be published before the NGINX that provides it - An NGINX upgrade cannot be published if it would strand an already-published module
Exact pins also make verification meaningful — the verified-modules observatory records per module the NGINX version and platform it was built and tested against, the binary hash, and which levels passed (config inventory, multi-worker runtime, sanitizers, lifecycle torture suite).
Installation
RHEL/Rocky/AlmaLinux/CentOS:
sudo dnf install https://extras.getpagespeed.com/release-latest.rpm
sudo dnf install nginx nginx-module-brotli
Debian/Ubuntu: set up the APT repository, then sudo apt-get update and sudo apt-get install nginx nginx-module-brotli.
Migration from the ondrej PPA is covered by a migration guide; every published NGINX build links OpenSSL 3.5 LTS. Repository metadata is public; downloading packages requires an active subscription (100+ NGINX modules, each rebuilt for every NGINX release and pinned to it exactly, so an upgrade either installs a matching set or stops at the prompt).
Read the full article: NGINX Module Version Mismatch: When APT Lets It Through
