How to Install Nginx Google Pagespeed Module on Debian 11
You’ll get a working PageSpeed build, a clean Nginx configuration and a cache directory that actually writes. If you’ve ever tried the pre‑compiled Debian package only to see “module not found” errors after a kernel upgrade, this guide will save you a few headaches.
Prepping the system
Before anything else, bring the OS up to date. Updating eliminates mismatched library versions that often break the compile step later.
sudo apt update
sudo apt full-upgrade -y
Next install the tools you’ll need for building from source.
- build-essential gives you gcc and make.
- zlib1g-dev, libpcre3-dev, uuid-dev are required by Nginx itself.
- git lets us pull the PageSpeed sources.
sudo apt install -y curl dpkg-dev build-essential zlib1g-dev \
libpcre3 libpcre3-dev uuid-dev git unzip
Grab Nginx source and the PageSpeed module
I always keep the source tree under /usr/src so it’s easy to clean up later.
mkdir -p /usr/src/nginx && cd /usr/src/nginx
wget https://nginx.org/download/nginx-1.20.2.tar.gz
tar -xzf nginx-1.20.2.tar.gz
Now clone the PageSpeed repo and check out the stable branch. The latest-stable tag points to the most reliable release.
git clone https://github.com/apache/incubator-pagespeed-ngx.git
cd incubator-pagespeed-ngx
git checkout latest-stable
The repository contains a file called PSOL_BINARY_URL that tells us where to fetch the PageSpeed Optimization Library (PSOL). We need those binaries before we can compile.
cat PSOL_BINARY_URL # shows something like https://dl.google.com/dl/page-speed/psol/1.13.35.2-x86_64.tar.gz
Replace the URL with whatever you see and download it:
wget $(cat PSOL_BINARY_URL) tar -xzf 1.13.35.2-*.tar.gz
Build Nginx with PageSpeed as a dynamic module
Compiling as a dynamic module means you can enable or disable it without rebuilding Nginx later.
cd /usr/src/nginx/nginx-1.20.2 ./configure --with-compat \
--add-dynamic-module=../incubator-pagespeed-ngx make modules
When the build finishes, the shared object lives in objs/ngx_pagespeed.so. Move it to a place Nginx will load from:
sudo cp objs/ngx_pagespeed.so /usr/share/nginx/modules/
Create a tiny loader file so Nginx knows about the new module.
sudo tee /usr/share/nginx/modules-available/ngx-pagespeed.conf > /dev/null <<'EOF'
load_module modules/ngx_pagespeed.so;
EOF
Enable it by symlinking into modules-enabled:
sudo ln -s /usr/share/nginx/modules-available/ngx-pagespeed.conf \
/etc/nginx/modules-enabled/70-ngx-pagespeed.conf
Test the config and reload Nginx.
sudo nginx -t && sudo systemctl reload nginx
Global PageSpeed settings
Put the core directives in a separate file so you can include it in any server block.
sudo tee /etc/nginx/pagespeed.conf > /dev/null <<'EOF'
pagespeed on;
pagespeed FileCachePath /var/ngx_pagespeed_cache;
# Prevent stray headers from breaking the optimizer.
location ~ "\.pagespeed\." { add_header "" ""; }
location ~ "^/pagespeed_static/"{ }
location ~ "^/ngx_pagespeed_beacon$" { }
EOF
Create a writable cache directory for the module. If you skip this step Nginx will start but PageSpeed won’t actually store anything.
sudo mkdir -p /var/ngx_pagespeed_cache
sudo chown www-data:www-data /var/ngx_pagespeed_cache
Hook PageSpeed into your site
Edit the virtual host you want to accelerate (the default site works for a quick test).
sudo nano /etc/nginx/sites-available/default
Inside the server{} block add a single line:
include /etc/nginx/pagespeed.conf;
Save, then verify and restart.
sudo nginx -t && sudo systemctl reload nginx
Open ports if you’re using UFW
Most fresh Debian installs ship with the uncomplicated firewall enabled. Allow HTTP/HTTPS traffic so your site is reachable.
sudo ufw allow 80/tcp sudo ufw allow 443/tcp sudo ufw reload
Verify that PageSpeed is alive
A quick curl -I will show the X-Page-Speed header if everything is wired correctly.
curl -I http://your-server-ip/
You should see something like:
HTTP/1.1 200 OK Server: nginx/1.20.2
Content-Type: text/html
X-Page-Speed: 1.13.35.2-0
If the header is missing, double‑check the include line in your server block and make sure the cache directory is owned by www-data.
That’s it. You now have a lean Nginx build with Google PageSpeed compiled as a dynamic module, a dedicated cache folder, and a reusable config file you can drop into any future virtual host.
Happy tweaking, and may your pages load faster than your coffee brews!
