Which nginx versions are supported?

nginx 1.24+ on Linux x86_64 (Debian/Ubuntu or RHEL/Rocky), installed from the official nginx repository or your distribution packages. The `.so` module must match your exact nginx version — check `nginx -V` and download the matching build.

Why does the cache file need world-writable permissions?

Nginx worker processes typically run as `nobody` or `www-data`, while the worker runs as its own service user. Both processes need to read and write the shared cache file and Unix socket, so the file needs `chmod 666` and the parent directory `chmod 777`.

Why is the worker still showing X-PageSpeed: MISS on every request?

Verify the worker is running with `systemctl status pagespeed-worker`, that `pagespeed_cache_path` and `--cache-path` point at the same file, and that the file is readable and writable by both processes. The shared config file `pagespeed-shared.conf` must also exist next to the cache file.

How do I upgrade to a new ModPageSpeed version?

Replace `ngx_pagespeed_module.so` in `/usr/lib/nginx/modules/` and `factory_worker` in `/usr/local/bin/`, then reload nginx and restart the worker. The cache file is preserved across upgrades — no need to clear it.

How is the worker socket path shared with nginx?

The worker writes `pagespeed-shared.conf` next to the cache file on startup. Nginx reads this file automatically via `pagespeed_cache_path` and polls it every ~1 second for changes, so no separate nginx directive is needed.

Install the nginx module — ModPageSpeed 2.0

Install the nginx module

Install the ModPageSpeed 2.0 dynamic module into your existing nginx.

Not available in 2.0 v1.0.0

The standalone nginx 2.0 module described on this page is not part of the v1.0.0 release. v1.0.0 ships the ASP.NET Core middleware (NuGet) and the Docker / nginx reverse proxy stack. For native nginx on bare-metal or VM today, use mod_pagespeed 1.1 — the production-hardened native module that covers Apache, nginx, IIS, and Envoy.

This page is retained for the future 2.x release that adds a standalone nginx module.

When this is available

The standalone nginx 2.0 module is deferred to a future 2.x release. Until then:

For native nginx today, see mod_pagespeed 1.1 — ships a dynamic module for nginx 1.26+.
For ModPageSpeed 2.0 today, see Docker installation.