Install ngx_pagespeed on Debian

Before you start

You need root (or sudo) and curl. The packaged module is a dynamic .so built and version-pinned against Debian'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.

Add the signed repository

One bootstrap command adds the repository. It detects your distribution, writes the apt source to /etc/apt/sources.list.d/modpagespeed.list, and imports the We-Amp signing key into /usr/share/keyrings/ so apt verifies every package against it.

# Add the signed repository
curl -fsSL https://packages.modpagespeed.com/install.sh | sudo sh

Supported: Debian 11 (bullseye), 12 (bookworm), and 13 (trixie) on amd64 and arm64. The source is pinned to your host's native architecture, so a multi-arch box fetches only its own index.

Install the module

Install the module with apt. The package name is identical on every supported distribution:

sudo apt install nginx-module-pagespeed

This is the nginx module. The Apache module is a separate package, mod-pagespeed, from the same repository — installing one never pulls in the other, and the two are not interchangeable.

Load the module in nginx

The .so installs to /usr/lib/nginx/modules/. The package ships a load snippet at /usr/share/nginx/modules-available/mod-pagespeed.conf and symlinks it into /etc/nginx/modules-enabled/, which stock Debian nginx includes automatically — no manual edit on a stock install.

# What the package drops in for you
load_module modules/ngx_pagespeed_module.so;

If you run nginx from a third-party repository that does not include /etc/nginx/modules-enabled/, add that load_module line yourself at the top of /etc/nginx/nginx.conf, in the main context. It must sit outside any http {} or server {} block, or nginx rejects the config.

Minimal pagespeed configuration

Enable PageSpeed in the http {} context — in /etc/nginx/nginx.conf or an included conf.d/*.conf file:

# http {} context
pagespeed on;
pagespeed FileCachePath /var/cache/ngx_pagespeed;
pagespeed RewriteLevel CoreFilters;

CoreFilters is the safe default filter set. The cache directory is created and chowned to the worker user automatically, so the path above works as-is. For the full directive list and filter reference, see 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

The module fails to load or reports a version mismatch

nginx logs an emerg at startup — module ... is not binary compatible or version NNN instead of MMM. The packaged .so is pinned to your distribution's stock nginx down to the patch version, and --with-compat does not relax this. It almost always means nginx came from a third-party repository at a different version. Reinstall the distribution's stock nginx, or build the module from source against the nginx you run.

No X-Page-Speed header on responses

Confirm the module is loaded with nginx -T | grep pagespeed, that pagespeed on; is set in the active config, and that you are testing an eligible HTML response (not an already-minified asset, a 304, or a proxied error page). On a third-party nginx the auto-include of modules-enabled/ may be missing — add the load_module line manually as shown above.

Cache directory or permission errors

The package creates FileCachePath and assigns it to the worker user at config-parse time, so a default install needs no manual setup. Errors here mean the parent path is not writable by the master process, the path is on a read-only or noexec mount, or a custom path points where nginx cannot create it. Point FileCachePath at a writable local directory such as /var/cache/ngx_pagespeed.

Other versions and architectures

The signed packages cover Debian 11 (bullseye), 12 (bookworm), and 13 (trixie) on amd64 and arm64. On a release outside that list, build the module from source against your nginx; the walkthrough covers it. 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 Debian?

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

Why won't the ngx_pagespeed module load on Debian?

The packaged .so is built against your distribution's exact stock nginx version, and nginx refuses to load a module built for any other version. If nginx came from a third-party repository the versions won't match — reinstall the distro's stock 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 nginx-module-pagespeed support arm64 on Debian?

Yes. Every supported Debian release ships both amd64 and arm64 builds, and the bootstrap pins the source to your host's native architecture.

Which Debian versions are supported?

Debian 11 (bullseye), 12 (bookworm), and 13 (trixie), on amd64 and arm64. For a release outside that list, build the module from source.

Do I still need to compile ngx_pagespeed from source on Debian?

No. A signed prebuilt package is maintained: add the We-Amp repository and run apt install nginx-module-pagespeed. Compiling from source is only needed for releases or architectures outside the supported matrix, or when you run a non-stock nginx.