ngx_pagespeed: PageSpeed Module for NGINX

Automatic image, CSS, JavaScript, and cache optimization at the NGINX edge.

Maintained packages, preserved reference

GetPageSpeed ships nginx-module-pagespeed as a version-matched NGINX dynamic module. This site also preserves the original Apache PageSpeed directive and filter reference under the Apache License 2.0. The archived upstream docs remain useful; the package, release channel, and installation guidance on this page are maintained by GetPageSpeed.

• Version-matched packages

  ---

  Install a prebuilt module that matches the GetPageSpeed NGINX package. No source build or PSOL toolchain required.

• 50+ optimization filters

  ---

  Rewrite images, CSS, JavaScript, HTML, and cache headers without changing application code.

• Progressive rollout

  ---

  Start conservatively, verify the result, then enable only the filters that help your workload.

• Complete reference

  ---

  Browse configuration, operations, troubleshooting, and every filter from the navigation tree.

PageSpeed module vs PageSpeed Insights

These are different products with similar names:

• ngx_pagespeed is an NGINX module. It rewrites responses and resources on your server.
• PageSpeed Insights is an external auditing tool. It measures a page and recommends changes, but it does not optimize your traffic.

You can use an audit to measure the result of ngx_pagespeed, but installing the module does not guarantee a particular audit score. Performance depends on the site, enabled filters, caching, and third-party scripts.

Choose a release track

Track	Codebase	Architectures	Current package availability	Best for
Stable	Original PSOL-based 1.14.36.2 line	x86_64	Stable GetPageSpeed RPM repository; APT where published	Existing production deployments that value compatibility
v2 beta	Maintained ngx_pagespeed 2.1 line with integrated libpagespeed	x86_64 and ARM64	EL9 testing RPMs and Ubuntu 24.04 testing APT packages	Evaluation, ARM64, and testing the maintained codebase

The v2 channel is opt-in

The v2 package is a beta and does not replace the stable package unless you explicitly enable the testing channel. Validate it on staging before a production rollout.

Five-minute install and safe rollout

1. Install the package

Package downloads on subscription-gated distributions require an active NGINX Extras subscription.

RPM stableRPM v2 beta (EL9)Debian / Ubuntu

sudo dnf install -y https://extras.getpagespeed.com/release-latest.rpm
sudo dnf install -y nginx-module-pagespeed

sudo dnf install -y https://extras.getpagespeed.com/release-latest.rpm
sudo dnf install -y --enablerepo=getpagespeed-extras-testing \
  nginx nginx-module-pagespeed

sudo apt-get update
sudo apt-get install nginx-module-pagespeed

The APT package enables its module-loading snippet automatically. The v2 beta is currently published only in the opt-in Ubuntu 24.04 testing suite.

2. Load the module on RPM systems

Add this at the top level of /etc/nginx/nginx.conf, before the events and http blocks:

load_module modules/ngx_pagespeed.so;

The APT package manages the equivalent file under /etc/nginx/modules-enabled/.

3. Start with the conservative rewrite level

Add the PageSpeed directives to the server block you want to optimize. The package creates /var/cache/pagespeed with the required ownership.

server {
    listen 443 ssl;
    server_name www.example.com;

    pagespeed on;
    pagespeed FileCachePath /var/cache/pagespeed;
    pagespeed RewriteLevel OptimizeForBandwidth;

    # Serve PageSpeed-generated resources through the module.
    location ~ "\.pagespeed\.([a-z]\.)?[a-z]{2}\.[^.]{10}\.[^.]+" {
        add_header "" "";
    }
    location ~ "^/pagespeed_static/" { }
    location = /ngx_pagespeed_beacon { }

    # Your existing locations follow.
}

OptimizeForBandwidth changes resource contents without changing their URLs, which makes it a safer first production step. After validation, move to CoreFilters or choose explicit filters.

4. Validate and reload NGINX

sudo nginx -t
sudo systemctl reload nginx

If nginx -t reports an unknown pagespeed directive, confirm that the load_module line is present and that the module package matches the installed NGINX build.

5. Prove that PageSpeed is active

curl -sI https://www.example.com/ | grep -i '^x-page-speed:'

An X-Page-Speed response header confirms that the module handled the HTML response. Then inspect an HTML page for .pagespeed. resource URLs or compare the transfer size before and after enabling your chosen filters. A first request may populate the cache before later requests show the optimized asset.

Roll out filters without surprises

1. Begin with OptimizeForBandwidth. It minimizes CSS, JavaScript, and images in place while preserving resource URLs.
2. Test CoreFilters on staging. It enables a broader default set and can rewrite URLs and HTML.
3. Use PassThrough for precise control. Enable a small, measured set with pagespeed EnableFilters ...;.
4. Protect known-sensitive paths. Exclude admin, checkout, signed URL, or application endpoints with Disallow rules.
5. Measure real users. Compare origin CPU, cache hit behavior, transferred bytes, Core Web Vitals, and error rates. Keep only improvements you can observe.

Compare rewrite levels and configure filters Browse every filter

Find the right reference

• Configuration

  ---

  Enable the module, control response headers, honor CSP, and configure virtual hosts.

  Module configuration

• Images

  ---

  Recompress images, generate modern formats, resize responsively, and lazy-load below-the-fold media.

  Image optimization

• CSS and JavaScript

  ---

  Minify, combine, inline, defer, and prioritize browser-critical assets.

  Filter catalogue

• Domains and caching

  ---

  Map origins, tune the file cache, configure downstream caches, and handle HTTPS resources.

  System settings

• Operations

  ---

  Expose protected statistics, inspect messages, and diagnose failed fetches or rewrites.

  Admin pages

• Troubleshooting

  ---

  Diagnose missing headers, unchanged resources, fetch failures, proxy behavior, and compatibility issues.

  FAQ

Practical filter starting points

Goal	Start with	Read first
Lowest-risk compression	OptimizeForBandwidth rewrite level	Optimize for bandwidth
Smaller images	rewrite_images	Optimize images
Responsive image variants	responsive_images	Responsive images
Smaller CSS and JavaScript	rewrite_css,rewrite_javascript	Configuring filters
Fewer render-blocking scripts	defer_javascript	Defer JavaScript
Longer static-asset caching	extend_cache	Extend cache

Treat filter sets as application changes

Filters can change HTML, URLs, script execution order, cache keys, and image output. Test authenticated pages, checkout flows, CSP-protected pages, JavaScript-heavy applications, and cache purge behavior before broadening a rollout.

Production checklist

• The module package and NGINX package come from the same GetPageSpeed channel.
• load_module is top-level and nginx -t succeeds.
• /var/cache/pagespeed is writable by the NGINX worker user and has enough disk space.
• PageSpeed resource and beacon locations are present.
• Admin and statistics endpoints are either disabled or access-restricted.
• HTTPS origins, reverse proxies, CDNs, and downstream caches are covered by the relevant configuration.
• Sensitive URLs are excluded before broader filters are enabled.
• The rollback is known: change pagespeed on; to pagespeed standby; and reload NGINX while existing .pagespeed. URLs continue to resolve.

Reference provenance

The detailed pages in this section are a Markdown preservation of the original Apache incubator-pagespeed-mod documentation, licensed under Apache 2.0. Apache retired that upstream project; GetPageSpeed maintains the packaging guidance and publishes version-matched NGINX module builds separately.

Some preserved pages describe Apache syntax alongside NGINX syntax. For this package, use directives beginning with lowercase pagespeed and the NGINX configuration examples.