The recommended way to add ngx_pagespeed to a new Nginx deployment is to install the maintained nginx-module-pagespeed package from the signed repository, then enable it with a small configuration. The package is prebuilt, so you normally do not need to compile Nginx or the PageSpeed Optimization Library (PSOL).
Need a server to try this on? Antihost offers Linux VPS plans with NVMe storage, full root access and a 14-day free trial.
The original open-source ngx_pagespeed repository is archived. The maintained continuation is mod_pagespeed 2.1, which keeps the familiar pagespeed directives and filter names. Use a source build only when your Nginx distribution is unsupported or you run a custom Nginx binary.
As an Amazon Associate I earn from qualifying purchases.
What you are installing
ngx_pagespeed is an Nginx module that rewrites responses and related assets using PageSpeed filters. It can optimize items such as HTML, CSS, JavaScript and images according to the filters enabled in your configuration. The maintained module is distributed as nginx-module-pagespeed and is designed to be loaded dynamically by Nginx.
For a new installation, use the maintained package rather than compiling the archived Google-era module. The maintained continuation is mod_pagespeed 2.1; existing configurations continue to use the pagespeed directive family. The legacy code has had no security patches since 2020 and lacks current features, so it is best reserved for compatibility with an existing deployment.
The module is free software. Optional commercial support and hardened builds are separate services and are not required to install or run the module.
Choose the installation path
| Situation | Recommended path | Important constraint |
|---|---|---|
| Supported Ubuntu, Debian or Enterprise Linux host using the distribution Nginx build | Install the signed nginx-module-pagespeed package |
The module is built for the distribution’s stock Nginx binary |
| Unsupported distribution or a custom Nginx build | Compile a dynamic module from the maintained source | Build against the exact Nginx source version you run |
| Existing legacy ngx_pagespeed deployment | Follow the package-swap migration | Remove the old module and leave exactly one current load_module line |
Installing the package is preferable whenever your host is covered. It avoids building PSOL and avoids rebuilding the module for every ordinary Nginx upgrade.
Check whether your distribution is supported
The current signed-package support list covers these combinations:
| Distribution family | Releases | Architectures |
|---|---|---|
| Ubuntu | 22.04 and 24.04 | amd64 and arm64 |
| Debian | 11, 12 and 13 | amd64 and arm64 |
| Enterprise Linux 9 | AlmaLinux, Rocky Linux and RHEL | x86_64 and aarch64 |
| Enterprise Linux 10 | EL10 distributions | x86_64 |
If your operating-system release or architecture is outside these combinations, plan on the source-build route. Also check how Nginx was installed: a module compiled for the stock distribution package can be incompatible with an Nginx binary from another repository.
Install the maintained package
1. Add the signed repository
Run the maintainer’s installer:
curl -fsSL https://packages.modpagespeed.com/install.sh | sudo shThe command adds the repository used for the signed module packages. Review your organization’s policy for piping a downloaded script to a shell; if your policy disallows it, obtain and audit the installer through your normal package-management review process before execution.
2. Install the module package
On Debian or Ubuntu, install the package with APT:
sudo apt install nginx-module-pagespeedOn AlmaLinux, RHEL or another supported Enterprise Linux system, use DNF:
sudo dnf install nginx-module-pagespeedThe package supplies the compiled module and its PageSpeed support files. You do not need to build PSOL separately for this path.
3. Confirm that Nginx loads the module
Distribution packages commonly install a line similar to:
load_module modules/ngx_pagespeed_module.so;That directive belongs in Nginx’s main context: place it at the top level of nginx.conf, outside both http {} and server {}. Some packages enable it through a file under modules-enabled. If your Nginx installation does not use that directory, add the line yourself in the main configuration.
Do not add the same module twice. Duplicate load_module directives can cause an error when Nginx parses its configuration. The package is tied to the distribution’s stock Nginx build; a third-party Nginx executable may reject the module even when the operating system itself is supported.
Recommended Free Tools
Add a minimal ngx_pagespeed configuration
Put the PageSpeed directives in the http {} context or in a file included from it. The following is a conservative starting point:
pagespeed on;
pagespeed FileCachePath /var/cache/ngx_pagespeed;
pagespeed RewriteLevel CoreFilters;
location ~ "\.pagespeed\.([a-z]\.)?[a-z]{2}\.[^.]{10}\.[^." ]+" { add_header "" ""; }
location ~ "^/pagespeed_static/" { }
location ~ "^/ngx_pagespeed_beacon$" { }What each directive does
pagespeed on;enables processing. Without it, the module may be loaded but will not optimize responses.pagespeed FileCachePath /var/cache/ngx_pagespeed;selects the on-disk cache. The Nginx worker user must be able to create and write files there.pagespeed RewriteLevel CoreFilters;enables the maintainer’s safe baseline filter set. Start here before considering more aggressive settings.- The first regular-expression location handles rewritten PageSpeed asset URLs and suppresses inherited headers for that location.
- The
/pagespeed_static/location serves static PageSpeed resources. - The
/ngx_pagespeed_beaconlocation permits the module’s beacon endpoint.
If you use a separate included file, make sure it is included inside http {} for the pagespeed directives and locations. Keep only the load_module directive at the main configuration level.
Prepare the cache directory
The cache path must exist and be writable by the account used by your Nginx workers. If that account cannot write to /var/cache/ngx_pagespeed, optimization requests can fail even though the module itself loads correctly. Use the ownership and permission convention already used by your distribution’s Nginx service rather than granting broad write access.
Test, reload and verify optimization
1. Validate the complete configuration
Always test before reloading:
sudo nginx -tProceed only when Nginx reports that the syntax test is successful. A failed test leaves the running worker on its previous configuration, but it should be fixed before any reload attempt.
2. Reload Nginx
sudo systemctl reload nginxA reload applies the module and PageSpeed settings without stopping the service. If your installation is not managed by systemd, use the reload mechanism supplied by that installation after the same successful syntax test.
3. Check the response header
Request the site and inspect the headers:
curl -sI https://yoursite/ | grep -i x-page-speedA version value in X-Page-Speed indicates that the PageSpeed worker is optimizing the response. Replace https://yoursite/ with the HTTPS URL you are testing. Test a response that is actually handled by the Nginx server containing the module, not a separate proxy or CDN that could hide or replace headers.
If the header is absent, first confirm that the module is loaded, pagespeed on; is active in the relevant context, and the request reaches the intended server block. Then inspect the Nginx error log for configuration, permission or cache-path errors.
Build the module for a custom Nginx
Use a source build when your distribution is not covered by the signed packages or when you deliberately run a custom Nginx binary. Install a compiler and the development dependencies required by the maintained module source, obtain that source, and build a dynamic module against the exact Nginx source release installed on the host.
What’s actually slowing this PC down?
Pick the symptom - the matching free tool is one click away.
Rank #3
- Upgraded Two Zipper Pockets: Forvencer server books feature two secure zipper pockets for better organization of coins, cash, and receipts, ensuring that everything you collect has a safe and secure place
- Smart Storage & Quick Access: Designed with 8 multi-functional compartments, the right side includes a guest receipt pad, while the left has a money pocket, ticket pocket, and credit card slot. Two small clear pockets store bills, receipts, and other visible items. A stitched pen loop ensures you always have your favorite pen ready
- High-quality & Easy to Clean: Crafted from high-quality PU leather with heavy-duty stitching, this server book is built to last. It resists tears, scratches, and its waterproof surface makes cleaning easy with just a damp cloth or a non-chlorine sanitizer
- Perfect Fit for Your Apron: Measuring 5” x 8”, this compact organizer is slightly smaller than other models, making it ideal for bending or sitting while carrying in your server apron. It holds everything a waitress needs—a place for everything
- What's Included: This server organizer comes with multiple open and zippered pockets to store money, receipts, tips, etc. Clear sleeves are perfect for keeping menus or special lists while serving. Available in a variety of colors, allowing you to express yourself even when in uniform
Example build sequence
The documented pattern below uses Nginx 1.26.3. Replace that directory with the exact source version used by your running binary:
cd ../nginx-1.26.3
./configure --add-dynamic-module=../ngx_pagespeed --with-compat
make modules
sudo cp objs/ngx_pagespeed_module.so /usr/lib/nginx/modules/--add-dynamic-module tells Nginx to compile the PageSpeed module as a loadable object. --with-compat requests dynamic-module compatibility, but it does not make unrelated Nginx versions interchangeable. A module built for one Nginx version should be rebuilt whenever Nginx is upgraded.
Load and configure the resulting object
Add the following at the main level of nginx.conf:
load_module modules/ngx_pagespeed_module.so;Then add the same minimal pagespeed directives and locations inside http {} or an included file, run the syntax test, reload, and check X-Page-Speed:
sudo nginx -t
sudo systemctl reload nginx
curl -sI https://yoursite/ | grep -i x-page-speedKeep the module file and the Nginx binary from the same build pairing. After every Nginx version change, repeat the module build and verify that the new object is the one loaded by the service.
The Tool Desk
Outbyte Driver Updater FREEFix the driver behind crashes, sound loss and screen glitchesFind Drivers →Outbyte PC Repair FREEClear out junk files and repair common Windows errorsFree Scan →Migrate an old ngx_pagespeed installation
An existing open-source installation can be moved to the maintained package without rewriting its PageSpeed configuration.
- Remove the old ngx_pagespeed module package or manually installed module according to the way it was originally installed.
- Add the signed repository with
curl -fsSL https://packages.modpagespeed.com/install.sh | sudo sh. - Install
nginx-module-pagespeedusing APT on Debian/Ubuntu or DNF on Enterprise Linux. - Retain your existing
pagespeeddirectives and filter names, checking that any custom paths still exist and are writable. - Ensure exactly one
load_moduleline names/usr/lib/nginx/modules/ngx_pagespeed_module.so(or the equivalent path used by your package). - Run
sudo nginx -t, reload Nginx, and verifyX-Page-Speed.
Do not leave both the legacy object and the maintained object enabled. Loading two PageSpeed modules can produce duplicate-symbol or duplicate-directive errors and makes it unclear which implementation is serving traffic.
Troubleshoot common failures
Nginx says the module file is missing
Check the path in load_module against the package’s actual module directory. A relative path such as modules/ngx_pagespeed_module.so is resolved relative to Nginx’s configured prefix. If the package installed the object elsewhere, use that package path consistently and remove stale load lines.
Nginx reports an “invalid module” or version mismatch
This usually means the module was compiled for a different Nginx build. A distribution package can be incompatible with an Nginx binary from a third-party repository, while a source-built module can become incompatible after an Nginx upgrade. Install the matching stock Nginx build or rebuild the dynamic module against the exact source version you run.
Do these 3 things before closing this tab:
1Clear out junk files and repair common Windows errors2Fix the driver behind crashes, sound loss and screen glitches3Repair Windows errors before they cause bigger problemsnginx -t rejects a pagespeed directive
Verify that the module’s load_module line is present at the top level and appears before configuration that uses PageSpeed directives. Also check context: load_module cannot be placed inside http or server, while pagespeed settings belong in http or server as documented.
Rank #4
The cache cannot be written
Confirm that /var/cache/ngx_pagespeed exists and is writable by the Nginx worker account. Correct the directory’s ownership and permissions using your operating system’s normal Nginx service conventions, then test and reload again.
No X-Page-Speed header appears
- Confirm the request reaches the Nginx instance where the module is loaded.
- Check that
pagespeed on;is in the active configuration context. - Run
sudo nginx -tand inspect the error log for cache or permission errors. - Repeat the header check against a direct origin URL if another proxy may be changing response headers.
The old configuration works but the package migration fails
Remove the old module reference before adding the maintained one, then search all included Nginx configuration files for duplicate load_module lines. Keep the established PageSpeed directives only after confirming that their cache and include paths are valid on the new host.
Operational decisions after installation
When the package is the better choice
Use the signed package when your host is supported and uses the distribution Nginx build. It supplies a prebuilt module, avoids a separate PSOL build, and reduces maintenance work during normal Nginx updates.
Free tools Windows power users keep installed
One-click scans. No signup required.
When source compilation is justified
Compile a dynamic module when your operating system is outside the package matrix, your architecture is unsupported, or you need to match a custom Nginx build. Treat the module as part of that Nginx build: record the source version and rebuild it whenever the binary changes.
How to roll back safely
Before changing a production configuration, keep a copy of the last known-good Nginx configuration and module package state. If the new module fails the syntax test or produces errors, restore the previous load_module line and PageSpeed settings, run nginx -t, and reload only after the test succeeds.
Costs, licensing and support
The module itself is free software, so there is no license fee required for a package or source installation. Your normal costs are the host, storage used by the file cache and the administration time needed to test upgrades. The signed package route generally reduces that maintenance effort because PSOL is included and the module does not have to be rebuilt for each routine Nginx update.
We-Amp also offers optional PageSpeed module support and hardened, attested builds. Those services are not required for operation. If you need vendor assistance or compliance-oriented binaries, check the provider’s current support terms and coverage for your exact operating system and architecture before budgeting them.
PC Slower Than It Used to Be?
A free scan shows the junk files, broken settings and background clutter dragging Windows down - then fixes them in one click.Free scan · Windows 10 & 11Outdated Drivers Are Slowing You Down
One free scan finds every outdated or missing driver and matches the right update for your exact hardware.Free scan · exact hardware matchProduction rollout checklist
- Confirm that the operating system, release and CPU architecture appear in the supported package matrix.
- Confirm that Nginx came from the distribution package expected by the module repository, rather than an unrelated third-party build.
- Back up
nginx.conf, included files and the current module package state. - Install the signed package and verify that only one
load_moduledirective references the PageSpeed object. - Create the cache directory with the ownership and permissions used by the Nginx worker account.
- Start with
pagespeed RewriteLevel CoreFilters;and keep custom filters out until the basic path is working. - Run
nginx -t, reload, and checkX-Page-Speedfrom the origin server. - Watch the Nginx error log and the cache filesystem after rollout. A full or unwritable cache can stop optimization even when configuration syntax remains valid.
- For a source build, record the exact Nginx source version and repeat the module build whenever that version changes.
Apply the same sequence in staging first when possible. A clean syntax test confirms that Nginx can parse the configuration; the response-header check confirms that a real request is reaching the worker with PageSpeed enabled.
Configuration boundaries worth remembering
Many installation failures come from mixing the two configuration levels. Nginx parses load_module before it processes the http and server blocks, so the loader line must be at the main level and before any directives that depend on the module. PageSpeed settings and the three locations belong in http {} or a permitted server {} context. An included file is valid only when it is included from the correct parent context.
Relative module paths are resolved from Nginx’s configured prefix, not necessarily from /etc/nginx. If a package uses modules/ngx_pagespeed_module.so, do not copy that line blindly into a custom-prefix installation without confirming where the object is installed. Use the absolute package path or the relative path that matches the running binary’s prefix, and remove obsolete references after a migration.
Frequently overlooked details
- A successful package installation does not enable optimization by itself;
pagespeed on;must be active. - A loaded module does not guarantee a writable cache. File-system permissions are part of the installation.
- The module loader and PageSpeed directives have different valid configuration contexts.
- The package follows the stock distribution Nginx ABI. “Supported operating system” does not mean “every Nginx binary on that operating system.”
- Dynamic modules are version-specific. Rebuild after an Nginx upgrade when using the source path.
- Use the
X-Page-Speedresponse header as an operational check rather than assuming that a clean reload means optimization is active.
Frequently Asked Questions
Is ngx_pagespeed still maintained?
The original open-source ngx_pagespeed repository is archived. The maintained continuation is mod_pagespeed 2.1, which preserves the familiar pagespeed directives and filter names. The legacy code has not received security patches since 2020.
Quick wins for a faster PC:
Repair Windows errors before they cause bigger problemsFix Now →Scan for outdated or missing drivers - takes under a minuteDriver Scan →Clear out junk files and repair common Windows errorsFree Scan →Do I need to compile Nginx or PSOL?
Usually not. On a supported host using the distribution’s stock Nginx build, install the signed nginx-module-pagespeed package. It is prebuilt and includes the PageSpeed support files, so a separate PSOL build is unnecessary.
Where does the load_module line go?
Place load_module modules/ngx_pagespeed_module.so; in Nginx’s main context, outside http and server blocks, and before any configuration that uses PageSpeed directives. Do not load the same object twice.
Which operating systems have signed packages?
The listed combinations are Ubuntu 22.04 and 24.04, Debian 11 through 13, Enterprise Linux 9 distributions such as AlmaLinux, Rocky Linux and RHEL, and EL10 on x86_64. Ubuntu and Debian packages support amd64 and arm64; EL9 supports x86_64 and aarch64.
Why is X-Page-Speed missing from my response?
Check that the module is loaded, pagespeed on; is active in the server handling the request, and the cache directory is writable. Test the origin directly because a reverse proxy or CDN can remove or replace response headers, and inspect the Nginx error log.
Do these 3 things before closing this tab:
1Fix the driver behind crashes, sound loss and screen glitches2Repair Windows errors before they cause bigger problems3Scan for outdated or missing drivers - takes under a minuteCan I use the package with an Nginx binary from another repository?
Not reliably. The package is built for the distribution’s stock Nginx ABI. A third-party or custom binary may reject it; use the matching stock build or compile a dynamic module against the exact Nginx source version you run.
How often must a source-built module be rebuilt?
Rebuild it whenever the Nginx binary or source version changes. The –with-compat option helps with supported compatibility but does not make modules interchangeable across unrelated Nginx versions.
Is there a charge for ngx_pagespeed?
The module is free software. Optional commercial support and hardened, attested builds are separate offerings; review current provider terms if you need them.
The Bottom Line
For supported systems, install the signed nginx-module-pagespeed package, load it once at Nginx’s main level, enable CoreFilters with a writable cache, and verify the X-Page-Speed header after a successful nginx -t. Compile a dynamic module only for an unsupported or custom Nginx build, and rebuild it whenever Nginx changes.
Quick Recap
Product prices and availability are accurate as of the date/time indicated and are subject to change. Any price and availability information displayed on Amazon at the time of purchase will apply.
