Install ngx_pagespeed on Amazon Linux

Before you start

You need root (or sudo) and curl. The packaged module is a dynamic .so built and version-pinned against Amazon Linux's stock nginx, so the running nginx must be the distribution's own build, not one from a third-party repository. nginx need not be installed first — apt pulls the matching stock nginx as a dependency if it is absent.

# If nginx is already installed, confirm it is the distro build
nginx -v

A writable path for the file cache is the only other requirement, and the package handles it: the FileCachePath directory is created and assigned to the worker user at config-parse time, so no manual mkdir or chown is needed.

Build the module from source

A signed Amazon Linux package isn't in the repository, so the maintained module is built from source. Install the toolchain and headers first:

# Amazon Linux 2023
sudo dnf groupinstall -y "Development Tools"
sudo dnf install -y pcre2-devel zlib-devel openssl-devel libuuid-devel

# Amazon Linux 2
sudo yum groupinstall -y "Development Tools"
sudo yum install -y pcre-devel zlib-devel openssl-devel libuuid-devel

Build against the exact nginx version from nginx -v, configured --with-compat so the resulting .so loads into the stock Amazon Linux nginx binary. The from-source walkthrough covers fetching the module, configuring the build, running make modules, and copying the module into place.

Build ngx_pagespeed from source

Load the module in nginx

A from-source build does not auto-wire itself, so add the load_module directive yourself. It must sit in the main context — the top of /etc/nginx/nginx.conf, before the events and http blocks, never inside http {}:

# top of /etc/nginx/nginx.conf, main context
load_module modules/ngx_pagespeed.so;

nginx resolves a relative modules/ path against its configured prefix; the stock Amazon Linux nginx links that to /usr/lib64/nginx/modules/. Copy the .so you built there, or give load_module an absolute path.

Minimal pagespeed configuration

Turn the module on inside the http {} block, pointed at a cache directory the nginx worker can write:

# inside http { } in /etc/nginx/nginx.conf
pagespeed on;
pagespeed FileCachePath /var/cache/ngx_pagespeed;
pagespeed RewriteLevel CoreFilters;

CoreFilters is the conservative, safe-by-default rewrite level; the cache directory is created and assigned to the worker user at config-parse time. The configuration reference lists every directive and filter.

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 or "not binary compatible"

nginx: [emerg] module ... is not binary compatible means the .so was built against a different nginx than the one running. Re-check nginx -v, rebuild against that exact version, and confirm the build was configured --with-compat. If you replaced the stock Amazon Linux nginx with one from a third-party or nginx.org repo, the module has to be rebuilt against that binary instead.

X-Page-Speed header missing

Three usual causes: the module isn't loaded (confirm the load_module line is in the main context and nginx -t passes), pagespeed on; isn't set in http {}, or the response isn't eligible (non-HTML, already optimized, or carrying a no-transform cache-control). Test against a plain HTML page first.

Cache directory not writable

Permission denied on the cache path means the nginx worker user can't write FileCachePath. Point it at a writable directory and confirm ownership matches the worker user (grep ^user /etc/nginx/nginx.conf, usually nginx).

SELinux is blocking the cache

If SELinux is enforcing, nginx can be denied write access to the cache path. Confirm the denial in the audit log first (ausearch -m avc -ts recent), then give the directory an nginx-writable context and relabel it:

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

Other versions and architectures

Amazon Linux 2023 and Amazon Linux 2 both take the from-source path, on x86_64 and on Graviton (arm64) — the build matches whichever nginx you run.

If a signed prebuilt package fits your fleet, the maintained module installs directly on Ubuntu and Debian (amd64 and arm64) and on EL9 (x86_64 and aarch64) and EL10 (x86_64) — AlmaLinux, Rocky Linux, and RHEL — from the signed repository. The install hub has the per-distribution commands.

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

Why is there no nginx-module-pagespeed package for Amazon Linux?

There is no signed Amazon Linux package in the repository. On Amazon Linux the maintained module is built from source against your exact nginx version.

How do I build ngx_pagespeed from source on Amazon Linux?

Install the build toolchain, then compile the module against the nginx version from nginx -v, configured --with-compat, and load the resulting .so. The from-source walkthrough has the full sequence.

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

An nginx dynamic module is ABI-locked to one nginx version. If the .so was built against a different nginx — or you swapped the stock nginx for a third-party build — it will not load. Rebuild against the exact version from nginx -v with --with-compat.

How do I check ngx_pagespeed is working on Amazon Linux?

Request a page and look for the X-Page-Speed response header: curl -sI https://yoursite/ | grep -i x-page-speed. A version string means the worker is optimizing.

Is ngx_pagespeed free?

It is free to install and evaluate, and fully optimizes. It adds an X-PageSpeed-Warn: unlicensed header until a license is applied. A commercial license is required for production use, and the site keeps serving either way.

ngx_pagespeed or mod_pagespeed — which do I install for nginx?

For nginx you want the nginx module, built from source on Amazon Linux. mod-pagespeed is the separate Apache module. They are distinct packages — do not mix them.

Does ngx_pagespeed work on Amazon Linux 2, Amazon Linux 2023, and Graviton arm64?

Yes. Amazon Linux 2 and 2023 both use the from-source path, on x86_64 and on Graviton (arm64) — the build matches whichever nginx you run.