Install the nginx module — ModPageSpeed 2.0

Q: 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`.

Q: 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.

Q: 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.

Q: 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

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.15 — the 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.15 — ships a dynamic module for nginx 1.26+.
For ModPageSpeed 2.0 today, see Docker installation.

Either way, run a PageSpeed Insights test on your site first to see which failing audits the module will fix, and check the Core Web Vitals guide for the LCP, CLS, and INP playbook.

Frequently asked questions

Which nginx versions are supported?

nginx 1.26+ 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.