Skip to main content

Installation: nginx Module

Install the ModPageSpeed 2.0 dynamic module into your existing nginx.

This guide covers installing the ModPageSpeed 2.0 dynamic module into an existing nginx installation on a bare-metal server or VM.

Prerequisites

  • nginx 1.24+ (stable or mainline), installed from the official nginx repository or your distribution’s packages
  • Linux x86_64 (Debian/Ubuntu or RHEL/Rocky)
  • A ModPageSpeed license key (get a 14-day free trial)

Install the Module

Download the prebuilt module matching your nginx version:

# Check your nginx version
nginx -V 2>&1 | head -1

# Download the module (replace VERSION with your nginx version)
curl -Lo ngx_pagespeed_module.so \
  https://modpagespeed.com/releases/latest/ngx_pagespeed_module-VERSION.so

# Copy to nginx modules directory
sudo cp ngx_pagespeed_module.so /usr/lib/nginx/modules/
sudo chmod 644 /usr/lib/nginx/modules/ngx_pagespeed_module.so

Install the Factory Worker

Download and install the worker binary:

curl -Lo factory_worker \
  https://modpagespeed.com/releases/latest/factory_worker

sudo cp factory_worker /usr/local/bin/
sudo chmod 755 /usr/local/bin/factory_worker

Set Up the Shared Directory

Both nginx and the worker need read/write access to a shared directory for the cache file and Unix socket:

sudo mkdir -p /var/lib/pagespeed
sudo chmod 777 /var/lib/pagespeed

Pre-create the cache file with the right permissions:

sudo touch /var/lib/pagespeed/cache.vol
sudo chmod 666 /var/lib/pagespeed/cache.vol

The open permissions are necessary because nginx worker processes run as nobody (or www-data) while the Factory Worker typically runs as its own service user. Both need to read and write the cache file and socket.

Configure nginx

Add the module and PageSpeed directives to your nginx configuration:

# At the top of nginx.conf (before the events block)
load_module /usr/lib/nginx/modules/ngx_pagespeed_module.so;

# Inside your server block
server {
    listen 80;
    server_name example.com;

    # Enable PageSpeed
    pagespeed on;
    pagespeed_cache_path /var/lib/pagespeed/cache.vol;
    # Worker socket path is read from pagespeed-shared.conf automatically

    location / {
        proxy_pass http://127.0.0.1:8081;
        # ... your existing proxy settings
    }
}

You can also enable PageSpeed in specific location blocks instead of the entire server block if you only want to optimize certain paths.

Test the configuration and reload:

sudo nginx -t
sudo systemctl reload nginx

Configure the Factory Worker

Create a systemd service file at /etc/systemd/system/pagespeed-worker.service:

[Unit]
Description=ModPageSpeed Factory Worker
After=network.target

[Service]
Type=simple
ExecStart=/usr/local/bin/factory_worker \
  --socket /var/lib/pagespeed/pagespeed.sock \
  --cache-path /var/lib/pagespeed/cache.vol \
  --cache-size 1073741824
UMask=0000
Restart=on-failure
RestartSec=5

[Install]
WantedBy=multi-user.target

Enable and start the service:

sudo systemctl daemon-reload
sudo systemctl enable pagespeed-worker
sudo systemctl start pagespeed-worker

The UMask=0000 ensures the Unix socket is created with world-writable permissions so that nginx workers can connect to it.

Verify It Works

# First request — should be a cache miss
curl -I http://localhost/

# Look for:
# X-PageSpeed: MISS
# Second request — should be a cache hit
curl -I http://localhost/

# Look for:
# X-PageSpeed: HIT

Check the worker is running:

sudo systemctl status pagespeed-worker

Check the worker logs:

sudo journalctl -u pagespeed-worker -f

Worker Command-Line Flags

FlagDefaultDescription
--socket PATH/tmp/pagespeed.sockUnix socket path for nginx notifications
--cache-path PATH(required)Path to the Cyclone cache volume file
--cache-size BYTES1073741824 (1 GB)Maximum cache size in bytes
--helpPrint usage and exit

The --cache-path must match the pagespeed_cache_path in your nginx config. The worker socket path is shared with nginx automatically via pagespeed-shared.conf (written next to the cache file).

Upgrading

To upgrade to a new version:

  1. Download the new ngx_pagespeed_module.so and factory_worker binaries
  2. Replace the files in /usr/lib/nginx/modules/ and /usr/local/bin/
  3. Reload nginx: sudo systemctl reload nginx
  4. Restart the worker: sudo systemctl restart pagespeed-worker

The cache file is preserved across upgrades. There is no need to clear it.

Uninstalling

# Stop and disable the worker
sudo systemctl stop pagespeed-worker
sudo systemctl disable pagespeed-worker
sudo rm /etc/systemd/system/pagespeed-worker.service
sudo systemctl daemon-reload

# Remove the module and worker binary
sudo rm /usr/lib/nginx/modules/ngx_pagespeed_module.so
sudo rm /usr/local/bin/factory_worker

# Remove PageSpeed directives from nginx.conf, then reload
sudo nginx -t && sudo systemctl reload nginx

# Optionally remove the cache
sudo rm -rf /var/lib/pagespeed

Troubleshooting

nginx fails to start with “module not compatible”: The .so module must match your exact nginx version. Check nginx -V and download the matching module build.

No X-PageSpeed header: Ensure pagespeed on; is in your server or location block and the module is loaded. Check nginx -t for configuration errors.

X-PageSpeed: MISS on every request: Verify the worker is running (systemctl status pagespeed-worker) and that the cache file path matches between nginx config and worker flags. Check that /var/lib/pagespeed/cache.vol is readable and writable by both nginx and the worker, and that pagespeed-shared.conf exists next to the cache file.

Permission denied errors: The cache file needs 666 permissions and the shared directory needs 777. The worker’s systemd unit should have UMask=0000 so the socket is created world-writable.

Next Steps