Add ngx_pagespeed to Nginx: Package and Source Builds

Updated 9 November 2026 · Standard formula, shown below

ngx_pagespeed adds Google PageSpeed optimization features to Nginx, such as rewriting and compressing eligible site assets. You can add it to a maintained Nginx package build or compile it into Nginx from source, but it is not a drop-in module for every installed Nginx: the module must match the server’s version and build options. First check whether the project’s source and required dependencies are still available for your platform; ngx_pagespeed development and distribution have changed over time.

What You’ll Need

A Linux server, shell access with sudo privileges, and a working Nginx configuration backup.
The exact Nginx version and build configuration currently installed. Run nginx -v and nginx -V; the latter prints configure arguments.
Compiler tools and the development libraries required by the ngx_pagespeed release you plan to build. Follow that release’s documentation, since dependencies vary by version and distribution.
A trusted, compatible ngx_pagespeed source release and its corresponding PageSpeed Optimization Libraries (PSOL) archive, if required by that release.
A staging server or maintenance window, plus a way to restore the previous package or Nginx binary if validation fails.

Step-by-Step

Identify how Nginx is installed. Check your package manager, for example with dpkg -l nginx on Debian-based systems or rpm -q nginx on RPM-based systems. Record the package name, repository, version, and whether it is distribution-maintained or supplied by a third-party repository. Do not replace a maintained package with an unrelated binary without a rollback plan.
Check compatibility and current support. Compare your Nginx version, platform, and compiler requirements with the documentation for the exact ngx_pagespeed release. Verify that the source and matching PSOL files are obtainable from a trusted project or vendor source. If the project does not support your Nginx version or the dependencies cannot be verified, stop and use a supported alternative rather than forcing a build.
Prepare a safe build environment. Prefer a clean build host or staging copy with the same distribution and architecture as production. Install the compiler, make, and documented development packages. Save the output of nginx -V, copy the Nginx configuration, and note the current binary path and package version. Keep the production package manager responsible for the installed service.
Choose the package-maintained route where available. Search your distribution or approved repository for an Nginx package that explicitly includes ngx_pagespeed, or for a source-package recipe that builds the module with the maintained Nginx package. Read the recipe to confirm the module and Nginx versions match. Build the package using the distribution’s documented packaging tools, then install it through the package manager so upgrades and file ownership remain trackable. Avoid adding an unknown repository just to obtain a prebuilt module.
For a source build, get matching source and libraries. Download the Nginx source corresponding to the version you intend to run, plus the ngx_pagespeed source and its documented PSOL archive. Verify checksums or signatures when the publisher provides them. Extract the archives and follow the release’s own directory layout and build instructions; filenames and download locations can change, so do not rely on an old copy-and-paste URL.
Configure Nginx with the module. Reproduce the existing Nginx configure arguments shown by nginx -V, adapting paths and options only as needed. Add the ngx_pagespeed option specified by that release, commonly an add-on argument pointing at the module source directory. If building a dynamic module, use the supported dynamic-module option and preserve ABI compatibility. Do not omit existing TLS, HTTP/2, or other required build options accidentally.
Compile and stage the result. Run the documented configure command, then compile using the release instructions. For a dynamic module, install or copy the resulting module to a controlled module directory; for a static build, stage the new Nginx binary separately. Do not overwrite the production binary yet. A failed configure or compile is a signal to resolve dependency or compatibility issues, not to suppress compiler errors.
Load and configure the module. For a dynamic module, add the appropriate load_module directive near the beginning of the main Nginx configuration, using the actual module path. Static builds do not use this directive. Add the PageSpeed configuration directives in the appropriate http, server, or location context as documented. Start with the feature disabled or in a limited test location, and use a dedicated writable cache directory with restrictive ownership and adequate space.
Validate before serving traffic. Run nginx -t using the staged binary and intended configuration. Check the error log and confirm the module loads; a module built for a different Nginx ABI may be rejected. Test a staging hostname or local request, inspect response headers and the rendered page, and check logs for rewrite or cache errors. Compare behavior with the optimization disabled before enabling it broadly.
Deploy with a rollback route. Install the verified package through the package manager, or switch to the staged binary using your normal service deployment process. Reload Nginx only after a successful configuration test. Monitor error logs, CPU, memory, disk usage, and page behavior. If the service fails or content is altered incorrectly, disable the directives or restore the previous package and configuration, then restart or reload as appropriate.

Common Mistakes

Building against a different Nginx version or configure options, which can cause module-loading failures or missing features.
Assuming an old blog’s commands, repository, dependency list, or download links are still maintained and safe.
Replacing a package-managed Nginx binary by hand, leaving package upgrades able to overwrite it or the service using a different binary than expected.
Enabling optimization globally before checking pages that rely on scripts, stylesheets, cookies, or dynamically generated content.
Giving the cache directory incorrect ownership, or placing it on a filesystem that can fill up without monitoring.

Tips

Keep build instructions, source versions, checksums, configure arguments, and package artifacts together so you can reproduce or roll back the build.
Use a test location and enable one optimization at a time. Verify both desktop and mobile layouts and any critical interactive features.
Keep the original package and configuration available until the new build has passed a real traffic test.
Check whether a maintained package or supported alternative is a better fit before taking responsibility for a custom Nginx build.

Troubleshooting

“Module is not binary compatible” or a load failure: Rebuild the module against the exact Nginx source version and compatible configure options. Confirm that the running service uses the binary you inspected, then rerun nginx -t.

Configure reports missing libraries or headers: Install the development package named by the error and the module’s documentation, then rerun configure from a clean build directory. Do not substitute a random library version.

Nginx rejects a directive: Check that the module loaded successfully and that the directive is in a supported configuration context. Compare spelling and syntax with documentation for the specific module release.

The site returns errors or assets look broken: Disable the PageSpeed directives for the affected location, inspect Nginx logs and browser network requests, and retest with optimization off. Exclude problematic resources or features before trying again.

Build succeeds but the service still uses old behavior: Check the systemd unit or init script for its executable and configuration paths, confirm the deployed module is readable by Nginx, and reload only after nginx -t succeeds.

Frequently Asked Questions

Can I add ngx_pagespeed to an existing Nginx package without rebuilding?
Only if a compatible module package is available for that exact Nginx build. Otherwise, use a documented package build or compile a matching Nginx/module combination.

Is ngx_pagespeed included in every Nginx package?
No. Package contents vary by distribution and repository. Inspect the package documentation and build options rather than assuming the module is present.

Should I use a dynamic or static module?
Use the method supported by your Nginx build and the module release. Dynamic modules are installed separately but still need ABI compatibility; static builds require rebuilding Nginx with the module included.

Will a custom build receive normal package updates?
Not automatically. A source build needs a repeatable process to rebuild and test the module whenever Nginx or its dependencies change. A maintained package recipe can make that process easier.

How can I undo the change?
Remove or comment out the module load and PageSpeed directives, test the configuration, then reload Nginx. If you replaced the binary, restore the previous package or binary and verify the service path.

Is the module suitable for production today?
That depends on the release’s current maintenance status, compatibility, and your operational needs. Confirm support and source integrity first; do not deploy an unmaintained or unverifiable build to a critical server.

Method: the standard formula for this calculation, rounded as each result states. See how the calculators work or report an error.