Operating System Debian

Nginx PageSpeed Module on Debian 12: Retired, and What to Use Instead

The PageSpeed module for Nginx is retired and its repository archived. Here is what replaces it on Debian 12, plus how to compile Nginx with a third-party module.

If you are looking for a way to compile Nginx with the PageSpeed module (ngx_pagespeed) on Debian, the first thing to know is that the module is no longer a maintained upstream project. The Apache PageSpeed podling was retired on 17 March 2023, and the apache/incubator-pagespeed-ngx repository on GitHub was archived and made read-only on 10 April 2025. Debian 8, which the older versions of this guide targeted, is also long past end-of-life.

This guide explains what that means for a new server and shows how to get the same results on Debian 12 (the steps also apply to Debian 13) with features that Nginx and Debian still maintain: gzip and Brotli compression, HTTP/2, long-lived browser caching and modern image formats. A short section at the end covers compiling Nginx from source with a third-party module, for the cases where you really do need a custom build.

Status of the PageSpeed module for Nginx

PageSpeed started at Google and was donated to the Apache Software Foundation, where it lived in the Incubator as incubator-pagespeed-ngx (Nginx) and incubator-pagespeed-mod (Apache httpd). The Incubator lists the podling as retired, and the source repository contains a RETIRED.txt file that says the same. The archived code is still downloadable, but nobody at Apache or Google is fixing bugs or security issues in it, and it bundles its own copies of image and networking libraries that no longer receive updates through that project.

For those reasons you should not build the archived module into a server that faces the internet. The old build instructions also depended on a precompiled optimization library downloaded separately from Google, which is one more piece you can no longer rely on.

What PageSpeed did automatically can be split into two groups:

PageSpeed featureMaintained replacement
Compressing text responsesNginx gzip module, Brotli module packaged by Debian
Extending cache lifetime of static filesexpires / Cache-Control in Nginx plus file names that change when the content changes
Combining many small files to save connectionsHTTP/2, which sends many requests over one connection
Minifying CSS and JavaScript, inlining small resourcesYour site's build step or CMS plugin, run once at deploy time instead of on every request
Recompressing images and converting them to WebPConvert images when you upload or deploy them; let Nginx pick the right file per browser

Requirements

  • A server running Debian 12 (or Debian 13) with a user that can run sudo.
  • A domain name pointing at the server. The examples use example.com.
  • A TLS certificate if you want HTTP/2, because browsers only use HTTP/2 over HTTPS.

Install Nginx from the Debian repository

Debian 12 ships Nginx 1.22 as a normal package that receives security updates, so there is no need to compile anything for the features used below.

sudo apt update
sudo apt install nginx

Check that the service is running:

systemctl status nginx --no-pager

Enable gzip and Brotli compression

The Debian /etc/nginx/nginx.conf already contains gzip on;, but by default Nginx only compresses text/html. Open the file and extend the gzip block inside http { }:

sudo nano /etc/nginx/nginx.conf
gzip on;
gzip_vary on;
gzip_proxied any;
gzip_comp_level 5;
gzip_min_length 1024;
gzip_types text/plain text/css text/xml text/javascript application/javascript application/json application/xml application/rss+xml image/svg+xml;

Brotli usually produces smaller files than gzip for the same content and is supported by all current browsers over HTTPS. Debian packages the module, so install it instead of building it:

sudo apt install libnginx-mod-http-brotli-filter libnginx-mod-http-brotli-static

Create a small configuration file for it:

sudo nano /etc/nginx/conf.d/brotli.conf
brotli on;
brotli_comp_level 5;
brotli_min_length 1024;
brotli_types text/plain text/css text/xml text/javascript application/javascript application/json application/xml application/rss+xml image/svg+xml;

Nginx sends Brotli to browsers that advertise br in Accept-Encoding and falls back to gzip for the rest.

Turn on HTTP/2 and long-lived caching for static files

In the server block of your site (for example /etc/nginx/sites-available/example.com), enable HTTP/2 on the TLS listener and add a location for static assets. On the Nginx 1.22 package in Debian 12, HTTP/2 is a parameter of listen:

server {
    listen 443 ssl http2;
    listen [::]:443 ssl http2;
    server_name example.com;
    root /var/www/example.com;

    ssl_certificate     /etc/ssl/certs/example.com.crt;
    ssl_certificate_key /etc/ssl/private/example.com.key;

    location ~* \.(css|js|svg|woff2|png|jpg|jpeg|gif|webp|avif|ico)$ {
        expires 30d;
        add_header Cache-Control "public";
    }
}

From Nginx 1.25.1 onwards there is a separate http2 on; directive for the server block; use that form if you run a newer Nginx.

A 30-day lifetime is only safe when a changed file gets a new URL, which is what PageSpeed did by rewriting file names. Most build tools and CMS asset pipelines do this for you by adding a hash or version to the file name (app.3f9c1a.css). If your files keep the same name after an edit, use a shorter lifetime.

Serve WebP images without rewriting your HTML

PageSpeed converted images on the fly. The maintained approach is to create the WebP file once, next to the original, and let Nginx choose. Install the converter and convert an image:

sudo apt install webp
cwebp -q 80 /var/www/example.com/images/photo.jpg -o /var/www/example.com/images/photo.jpg.webp

Add a map to the http context, for example in /etc/nginx/conf.d/webp.conf:

map $http_accept $webp_suffix {
    default        "";
    "~*image/webp" ".webp";
}

Then, inside the server block, try the WebP file first for JPEG and PNG requests:

location ~* \.(png|jpe?g)$ {
    add_header Vary Accept;
    expires 30d;
    try_files $uri$webp_suffix $uri =404;
}

Browsers that send image/webp in their Accept header receive photo.jpg.webp; others receive the original file.

Test and reload

sudo nginx -t
sudo systemctl reload nginx

Check compression and caching headers from another machine:

curl -s -o /dev/null -D - -H "Accept-Encoding: br, gzip" https://example.com/style.css

The response should include content-encoding: br (or gzip if you request only gzip) and the cache-control and expires headers you configured. The first line shows HTTP/2 200 when HTTP/2 is in use.

If you still need to compile Nginx with a third-party module

Some modules are not packaged by Debian. The general procedure is the one the PageSpeed build used, minus PageSpeed itself. Install the build tools and libraries:

sudo apt install build-essential libpcre2-dev zlib1g-dev libssl-dev

Look up the current stable version on the nginx.org download page, set it in a variable, then download and unpack the source:

NGINX_VER=x.y.z
cd /usr/local/src
sudo wget https://nginx.org/download/nginx-${NGINX_VER}.tar.gz
sudo tar -xzf nginx-${NGINX_VER}.tar.gz
cd nginx-${NGINX_VER}

Configure the build with the modules you need. --add-dynamic-module points at the unpacked source of the third-party module and builds it as a loadable .so file; a separate prefix keeps the result away from the Debian package:

sudo ./configure \
  --prefix=/opt/nginx \
  --with-compat \
  --with-http_ssl_module \
  --with-http_v2_module \
  --with-http_gzip_static_module \
  --add-dynamic-module=/usr/local/src/your-module
sudo make -j "$(nproc)"
sudo make install

Confirm the configure arguments of the new binary:

/opt/nginx/sbin/nginx -V

Load the module with a load_module modules/<name>.so; line at the top of /opt/nginx/conf/nginx.conf. Each module documents its own extra dependencies in its README. Keep in mind that a self-compiled Nginx does not get updates from apt: you have to rebuild it yourself for every security release, and you need to write your own systemd unit for it.

Frequently asked questions

Can I still build the archived ngx_pagespeed code?

The source is still public, so a build may succeed against older Nginx releases, but nothing guarantees that it compiles or behaves correctly with current Nginx, OpenSSL and compilers, and nobody upstream will fix it if it does not. On a public server that is a risk without a matching benefit.

Is there a drop-in replacement that rewrites pages automatically?

Not in Nginx itself or in the Debian archive. Third parties offer their own continuations of the PageSpeed code and hosted optimization services; evaluate those like any other external dependency. For most sites the steps above plus a build-time asset pipeline cover the same ground with fewer moving parts.

Does the Apache module mod_pagespeed have the same status?

Yes. Both modules belonged to the same Apache Incubator podling, and the whole podling was retired together.

Why does HTTP/2 make file combining unnecessary?

Under HTTP/1.1 a browser opened only a handful of connections per host, so many small files queued behind each other. HTTP/2 multiplexes requests over a single connection, which removes most of that penalty and lets each file be cached on its own.

Share story:

Continue reading other guides on How VPS.