Install ngx_pagespeed on Rocky Linux

Before you start

You need root or sudo and curl on PATH. The signed RPM ships a dynamic module built and exact-version-pinned against the nginx Rocky Linux publishes, so nginx must be the distribution's own stock build (from AppStream), not a third-party repository build — a module is ABI-locked to one nginx version and will not load into a different build. dnf pulls the matching stock nginx as a dependency if it is absent.

# If nginx is installed, confirm it is the distro build and note the version
nginx -v

Have a writable directory ready for the file cache. On a stock EL install SELinux is Enforcing: keep the cache under a path nginx is already allowed to write, or relabel it — see Troubleshooting below.

Add the signed repository

One bootstrap command configures the repository. It reads /etc/os-release to detect the EL major version, writes /etc/yum.repos.d/modpagespeed.repo pointing at the matching $basearch tree, and imports the We-Amp signing key to /etc/pki/rpm-gpg/. Both the repository metadata and every RPM are GPG-verified (repo_gpgcheck=1 and gpgcheck=1).

# Detects the distro, writes the dnf repo, imports the signing key
curl -fsSL https://packages.modpagespeed.com/install.sh | sudo sh

Coverage: Rocky Linux 9 (x86_64 and aarch64) and Rocky Linux 10 (x86_64). One EL10 build serves RHEL, Rocky Linux, AlmaLinux, and CloudLinux 10. EL10 on arm64 and EL8 are not in the repository — build from source there (see below).

Install the module

With the repository configured, install the nginx module:

sudo dnf install nginx-module-pagespeed

The package name is the same on AlmaLinux, Rocky Linux, RHEL, and the binary-compatible rebuilds. The Apache module is a separate package, mod-pagespeed, from the same signed repository — install that one only if you run httpd. nginx-module-pagespeed is the nginx dynamic module; mod-pagespeed is the Apache module, and the two are not interchangeable.

Load the module in nginx

A dynamic module does nothing until nginx loads it. The package drops the module object at /usr/lib64/nginx/modules/ngx_pagespeed_module.so plus a load snippet at /usr/share/nginx/modules/mod-pagespeed.conf. Stock EL nginx.conf includes that directory from the main context (include /usr/share/nginx/modules/*.conf;), so the snippet is usually picked up automatically. Confirm it:

# Is the load snippet present, and does the module object exist?
grep -Rs load_module /etc/nginx/nginx.conf /etc/nginx/conf.d/ /usr/share/nginx/modules/
ls /usr/lib64/nginx/modules/ | grep -i pagespeed

If nothing loads it, add the directive yourself at the top of /etc/nginx/nginx.conf — in the main context, above events { } and http { }. load_module is invalid inside http { } and nginx will refuse to start:

# Main context — top of nginx.conf, NOT inside http {}
load_module /usr/lib64/nginx/modules/ngx_pagespeed_module.so;

Minimal pagespeed configuration

Turn the module on inside the http { } context: enable pagespeed, point the file cache at a writable directory, and start with a conservative rewrite level.

# Inside http { } in /etc/nginx/nginx.conf (or a conf.d/ include)
pagespeed on;
pagespeed FileCachePath /var/cache/nginx/pagespeed;
pagespeed RewriteLevel CoreFilters;

CoreFilters is the safe default filter set, and the cache directory is created and assigned to the worker user at config-parse time. Keeping it under /var/cache/nginx/ means it inherits a context nginx may write under SELinux. The full directive set — filter selection, cache sizing, rewrite scope — is in the configuration reference.

Reload and verify

Test the configuration, then reload nginx:

sudo nginx -t && sudo systemctl reload nginx

An optimized response then carries the X-Page-Speed header:

curl -sI https://yoursite/ | grep -i x-page-speed

A version string in that header means the worker is optimizing. If the header is absent, work through the troubleshooting steps below.

Troubleshooting

Module fails to load / "is not binary compatible"

The packaged .so is built against your distribution's stock nginx and pinned to that exact version. If nginx came from a third-party repository (for example the upstream nginx.org repo) the version will not match and nginx -t reports the module is not binary compatible. Either reinstall the distro's nginx (dnf install nginx from AppStream) so the pin is satisfied, or build the module from source against the nginx you actually run.

X-Page-Speed header absent

Three usual causes: the module is not loaded (re-check the load snippet is included and nginx -t passes), pagespeed on; is missing from http { }, or the response is not eligible (already optimized, an error status, or a content type pagespeed does not rewrite). A dynamically loaded module does not appear in nginx -V — rely on nginx -t and the response header to confirm it loads.

Cache directory not writable / permission denied

The worker writes the file cache as the nginx user. If the error log shows a permission error on the FileCachePath, the parent path is not writable by nginx. Point FileCachePath at a writable directory such as /var/cache/nginx/pagespeed.

SELinux denials on the cache path (EL)

On Enforcing SELinux, nginx can be denied write access to a FileCachePath that is not in a context it is allowed to write — even when filesystem ownership is correct. Check the audit log for a denial against the nginx process:

sudo ausearch -m avc -ts recent -c nginx

If denials appear, relabel the cache path to a context nginx may write, then restore the labels:

sudo semanage fcontext -a -t httpd_cache_t "/var/cache/nginx/pagespeed(/.*)?"
sudo restorecon -Rv /var/cache/nginx/pagespeed

Keeping the cache under /var/cache/nginx/ avoids this in the first place. For a denial that does not fit a standard relabel, generate a scoped local policy from the audit record with audit2allow rather than disabling SELinux.

Other versions and architectures

The signed RPM covers Rocky Linux 9 (x86_64 and aarch64) and Rocky Linux 10 (x86_64). AlmaLinux, Rocky Linux, RHEL, and the binary-compatible rebuilds (CentOS Stream, Oracle Linux, CloudLinux) share the build for their EL major. EL10 on arm64 and EL8 are not in the repository; on those, build the module from source against your nginx. See the install hub to install ngx_pagespeed on other Linux distributions.

Build ngx_pagespeed from source

1.1 nginx or 2.0 nginx?

Two maintained engines exist for nginx. mod_pagespeed 1.1 keeps the existing pagespeed_* directives, so current configs carry over. ModPageSpeed 2.0 is a new architecture (mmap serving, variant-aware caching, AVIF) for fresh installs.

Compare mod_pagespeed 1.1 vs 2.0 for nginx

Licensing

FAQ

Is nginx-module-pagespeed free?

It is free to install and evaluate, and it fully optimizes out of the box. Until a license is applied it adds an X-PageSpeed-Warn: unlicensed header; a commercial license is required for production use. Your site keeps serving either way.

How do I check ngx_pagespeed is working on Rocky Linux?

Probe for the response header: curl -sI https://yoursite/ | grep -i x-page-speed. A version string in that header means the worker is optimizing.

Why won't the ngx_pagespeed module load on Rocky Linux?

The packaged module is built against your distribution's stock nginx and pinned to that exact version. If nginx came from a third-party repository instead of AppStream, the versions mismatch and the module is rejected as not binary compatible. Reinstall the distro nginx, or build the module from source against the nginx you run.

ngx_pagespeed or mod_pagespeed — which do I install for nginx?

For nginx, install nginx-module-pagespeed. mod-pagespeed is the Apache module and ships as a separate package from the same signed repository. The two are not interchangeable.

Does it work on RHEL 9, RHEL 10, CentOS Stream, Oracle Linux, or CloudLinux?

Yes. EL9 is covered on x86_64 and aarch64, EL10 on x86_64. The binary-compatible rebuilds — CentOS Stream, Oracle Linux, CloudLinux — share the build for their EL major. EL10 on arm64 and EL8 are from-source only.

SELinux is blocking the pagespeed cache — how do I fix it?

Relabel the FileCachePath to a context nginx may write (semanage fcontext with a cache-content type, then restorecon -Rv), or keep the cache under /var/cache/nginx/, which already carries a writable context. Do not disable SELinux to work around it.

I'm on cPanel / EasyApache — which package?

The EasyApache 4 Apache module is a separate package built against EA4's bundled httpd, distinct from both the stock mod-pagespeed and the nginx nginx-module-pagespeed. Keep them distinct and install the one that matches the server you run.