Configuration

Load the module and enable it in your server block:

load_module modules/ngx_pagespeed.so;

http {
    server {
        pagespeed on;

        # Required location blocks
        location ~ "\.pagespeed\.([a-z]\.)?[a-z]{2}\.[^.]{10}\.[^.]+" {
            add_header "" "";
        }

        location ~ "^/pagespeed_static/" { }
        location ~ "^/ngx_pagespeed_beacon$" { }
    }
}

The distribution package loads the module automatically on install. Enable it in pagespeed.conf or your virtual host configuration:

ModPagespeed on

The installer registers the module in IIS automatically. Configure it through pagespeed.config, a flat-text configuration file with one directive per line.

The module looks for configuration files in this order:

1. Site-level: pagespeed.config in the website root directory
2. Server-level: %ProgramData%\We-Amp\IISWebSpeed\pagespeed.config

Site-level settings override server-level settings. If pagespeed.config is not found, the module falls back to iiswebspeed.config (legacy filename).

Enable optimization by adding to your pagespeed.config:

pagespeed on

pagespeed standby;

ModPagespeed standby

pagespeed standby

In nginx, prefix each directive with pagespeed and terminate with a semicolon.

pagespeed HonorCsp on;
pagespeed RespectVary on;
pagespeed DisableRewriteOnNoTransform on;
pagespeed LowercaseHtmlNames off;
pagespeed ModifyCachingHeaders on;
pagespeed XHeaderValue "Powered by mod_pagespeed";
pagespeed PreserveUrlRelativity off;
pagespeed StaticAssetPrefix "/pagespeed_static/";
pagespeed AddResourceHeader "X-Custom" "value";
pagespeed ListOutstandingUrlsOnError off;

In Apache, prefix each directive with ModPagespeed.

ModPagespeedHonorCsp on
ModPagespeedRespectVary on
ModPagespeedDisableRewriteOnNoTransform on
ModPagespeedLowercaseHtmlNames off
ModPagespeedModifyCachingHeaders on
ModPagespeedXHeaderValue "Powered by mod_pagespeed"
ModPagespeedPreserveUrlRelativity off
ModPagespeedStaticAssetPrefix "/pagespeed_static/"
ModPagespeedAddResourceHeader "X-Custom" "value"
ModPagespeedListOutstandingUrlsOnError off

In IIS, use pagespeed.config with one directive per line. Prefix each directive with pagespeed.

pagespeed HonorCsp on
pagespeed RespectVary on
pagespeed DisableRewriteOnNoTransform on
pagespeed LowercaseHtmlNames off
pagespeed ModifyCachingHeaders on
pagespeed XHeaderValue "Powered by mod_pagespeed"
pagespeed PreserveUrlRelativity off
pagespeed StaticAssetPrefix "/pagespeed_static/"
pagespeed AddResourceHeader "X-Custom" "value"
pagespeed ListOutstandingUrlsOnError off

The pagespeed.config format also accepts ModPagespeed and iispeed as directive prefixes for compatibility. The pagespeed prefix is recommended.

Apache supports configuration at several levels:

• pagespeed.conf — Global defaults that apply to all virtual hosts.
• <VirtualHost> — Per-site overrides.
• <Directory> and <Location> — Target specific filesystem paths or URL paths.
• .htaccess — Per-directory configuration placed in the document root or subdirectories.

.htaccess configuration is re-read on every request, which adds per-request overhead. For high-traffic sites, prefer <Directory> or <Location> blocks in the server configuration.

Example using <Location>:

<Location /images/>
    ModPagespeedDisableFilters convert_jpeg_to_webp
</Location>

In nginx, use server and location blocks to scope directives:

server {
    pagespeed on;

    location /static/ {
        pagespeed off;
    }
}

Directives set in a server block apply to all locations within that server unless overridden by a more specific location block.

IIS supports configuration at two levels:

• Server-level: %ProgramData%\We-Amp\IISWebSpeed\pagespeed.config — applies to all websites on the server.
• Site-level: pagespeed.config in the website root directory — overrides server-level settings for that site.

Within a configuration file, use match rules to scope directives to specific URLs or hostnames:

# Only optimize requests matching this host
hostname: ^www\.example\.com$

pagespeed on
pagespeed EnableFilters rewrite_images

# Match a specific URL path
path: ^/blog/

pagespeed EnableFilters prioritize_critical_css

Match rules use RE2 regular expressions. The hostname and path keys match against the request hostname and URL path respectively.

server {
    server_name site-a.example.com;
    pagespeed on;
    pagespeed EnableFilters rewrite_images;
}

server {
    server_name site-b.example.com;
    pagespeed on;
    pagespeed EnableFilters collapse_whitespace;
}

<VirtualHost *:80>
    ServerName site-a.example.com
    ModPagespeed on
    ModPagespeedEnableFilters rewrite_images
</VirtualHost>

<VirtualHost *:80>
    ServerName site-b.example.com
    ModPagespeed on
    ModPagespeedEnableFilters collapse_whitespace
</VirtualHost>

Place a pagespeed.config file in each website’s root directory. Each file can carry its own set of directives:

Site A (C:\inetpub\site-a\pagespeed.config):

pagespeed on
pagespeed EnableFilters rewrite_images

Site B (C:\inetpub\site-b\pagespeed.config):

pagespeed on
pagespeed EnableFilters collapse_whitespace

Alternatively, use match rules in the server-level config to scope directives by hostname:

hostname: ^site-a\.example\.com$
pagespeed EnableFilters rewrite_images

hostname: ^site-b\.example\.com$
pagespeed EnableFilters collapse_whitespace