Skip to main content
Docs menu

Upgrade and migrate

Last updated Edit this page View as Markdown

Upgrade mod_pagespeed per shape: apt or dnf, Docker tag, Helm, the Windows installer and NuGet; what to read first, security updates, rollback.

On this page

Where are you coming from

You runRead
mod_pagespeed 2.xThis page
mod_pagespeed 1.15Migrate from mod_pagespeed 1.15
The archived Google module (1.13 and earlier)Migrate from the archived Google module
ngx_pagespeedMigrate from ngx_pagespeed
IISpeedMigrate from IISpeed
ModPageSpeed 2.0Migrate from ModPageSpeed 2.0

The current release is v2.9.2. Upgrading is a package, image or chart update on whichever shape you run, with one rule across all of them: the module and the optimizer worker move together, and the optimizer starts first. Read the current release’s notes before you start; the one-time steps a release needs are listed under “Before you upgrade” in the release notes.

Before you upgrade

  • Read the release notes. A release that changes the cache format starts the cache empty once: the new optimizer opens a new volume beside the old one and never reads the old one, so the first requests after the upgrade are misses and the hit rate dips until the cache refills. The old files stay on disk, which is what makes a rollback warm; delete them once you will not roll back.
  • Check free space. Both volumes exist during such an upgrade, so the cache directory needs free space at least equal to the configured cache size on top of what the current volume occupies.
  • Pick a quiet hour if your origin is sensitive to the refill.
  • Plan to purge cached HTML in your CDN once the upgrade is done. See Hydrated pages.
  • Move both parts together, optimizer first. A module and an optimizer on different cache formats do not share a cache: the Apache module refuses to attach and says so; the native nginx module turns in-place optimization through the optimizer off and logs the reason; the reverse-proxy nginx keeps serving with its cache off and logs one error until the two agree. Starting the optimizer and then restarting the web server clears all three.

Apache and nginx packages

# Debian / Ubuntu
sudo apt-get update
sudo apt-get install --only-upgrade mod-pagespeed pagespeed-optimizer           # Apache
sudo apt-get install --only-upgrade nginx-module-pagespeed pagespeed-optimizer  # nginx

# AlmaLinux / RHEL / Rocky
sudo dnf upgrade mod-pagespeed pagespeed-optimizer            # Apache
sudo dnf upgrade nginx-module-pagespeed pagespeed-optimizer   # nginx

Upgrading or reinstalling the pagespeed-optimizer package turns the optimizer service back on and restarts it, even if you had turned it off. Then restart the web server: sudo systemctl restart apache2 (httpd on Enterprise Linux) or sudo systemctl restart nginx. At boot the packaged unit orders the optimizer ahead of apache2.service, httpd.service and nginx.service; during a hand-run upgrade that order is yours to keep: optimizer first, web server second.

The nginx module is built for the exact nginx version your distribution ships, and nginx refuses to load a module built for another version; see the compatibility table before you upgrade nginx itself.

On cPanel / EasyApache 4 the module is the ea-apache24-mod_pagespeed RPM in the opt-in ea4 repository: sudo dnf upgrade --enablerepo=ea4 ea-apache24-mod_pagespeed. See cPanel / EasyApache 4.

Docker

The worker and nginx images are tagged by release, and the two must run the same tag. Set it in deploy/.env and recreate the stack:

# deploy/.env
PAGESPEED_VERSION=2.9.2

docker compose -f deploy/docker-compose.yml pull
docker compose -f deploy/docker-compose.yml up -d

The named cache volume survives the recreate, and both containers share one PID namespace through the pidns container, so an upgrade that briefly mixes builds does not put the cache’s write lock at risk. The combined evaluation image is the one image published as :latest: docker pull ghcr.io/we-amp/pagespeed-combined:latest, then recreate its container.

Helm

helm repo update
helm upgrade pagespeed weamp/pagespeed -f my-values.yaml

Or move only the image tag. The chart takes one image.tag for both images (leave it unset to track the chart’s appVersion); the per-image worker.image.tag and nginx.image.tag keys are rejected, because a worker and an nginx on different builds break the async-CSS loader:

helm upgrade pagespeed weamp/pagespeed --reuse-values --set image.tag=2.9.2

The emptyDir cache is lost on pod restart and rebuilds as requests arrive. Deploy with Helm has the values.

IIS

Download the current MSI from the download page and run it over the existing install, then iisreset. An upgrade or repair keeps an optimizer service you turned on running and keeps the cache size you chose. The IIS package ships as a signed installer on the mod_pagespeed GitHub release.

ASP.NET Core

Update the package reference and redeploy:

dotnet add package WeAmp.PageSpeed.AspNetCore

Without a version, dotnet add package pins the newest release in the project file. The middleware launches the worker from the same package, so the two stay matched by construction.

Options that load with a warning

These options and filters from older configurations still load. The server logs a deprecation warning for each and starts normally, so a configuration that ran on 1.14 or on ngx_pagespeed keeps working while you clean it up. On Apache the directive names carry the ModPagespeed prefix, for example ModPagespeedFileCacheInodeLimit. A repeated directive is listed once: nginx has 33 such lines and Apache 44, which are 43 distinct names because LogMobilizationSamples appears twice on Apache. sudo nginx -t and sudo apachectl configtest print every warning, so run one before you restart.

OptionServerWhat happens now
AllowVaryOnnginx, ApacheWarns, does nothing
AnalyticsIDnginx, ApacheWarns, does nothing
CollectRefererStatisticsApacheWarns, does nothing
ContentExperimentIDnginx, ApacheWarns, does nothing
ContentExperimentVariantIDnginx, ApacheWarns, does nothing
DisableForBotsApacheWarns, does nothing
DistributedRewriteKeynginx, ApacheWarns, does nothing
DistributedRewriteServersnginx, ApacheWarns, does nothing
DistributedRewriteTimeoutMsnginx, ApacheWarns, does nothing
DistributeFetchesnginx, ApacheWarns, does nothing
ExperimentalCentralControllerPortnginx, ApacheWarns, does nothing
ExperimentalPopularityContestMaxInFlightnginx, ApacheWarns, does nothing
ExperimentalPopularityContestMaxQueueSizenginx, ApacheWarns, does nothing
ExperimentVariablenginx, ApacheWarns, does nothing
FetchFromModSpdyApacheWarns, does nothing
FileCacheCleanIntervalMsnginx, ApacheWarns, does nothing
FileCacheInodeLimitnginx, ApacheWarns, does nothing
GeneratedFilePrefixApacheWarns, does nothing
HashRefererStatisticsApacheWarns, does nothing
IncreaseSpeedTrackingnginx, ApacheWarns, does nothing
InheritVHostConfigApacheWarns, does nothing
LogMobilizationSamplesnginx, ApacheWarns, does nothing
MaxPrefetchJsElementsnginx, ApacheWarns, does nothing
NumShardsApacheWarns, does nothing
PrivateNotVaryForIEnginx, ApacheWarns, does nothing
RefererStatisticsOutputLevelApacheWarns, does nothing
ShardDomainnginx, ApacheWarns, still applies
StatisticsLoggingFileApacheWarns, does nothing
UrlPrefixApacheWarns, does nothing
UseAnalyticsJsnginx, ApacheWarns, does nothing
UseExperimentalJsMinifiernginx, ApacheWarns, does nothing
EnableFilters defer_iframenginx, ApacheWarns, does nothing
EnableFilters div_structurenginx, ApacheWarns, does nothing
EnableFilters explicit_close_tagsnginx, ApacheWarns, does nothing
EnableFilters flush_subresourcesnginx, ApacheWarns, does nothing
EnableFilters in_place_optimize_for_browsernginx, ApacheWarns, does nothing
EnableFilters insert_ganginx, ApacheWarns, does nothing
EnableFilters local_storage_cachenginx, ApacheWarns, does nothing
EnableFilters make_google_analytics_asyncnginx, ApacheWarns, does nothing
EnableFilters mobilizenginx, ApacheWarns, does nothing
EnableFilters mobilize_precomputenginx, ApacheWarns, does nothing
EnableFilters split_htmlnginx, ApacheWarns, does nothing
EnableFilters split_html_helpernginx, ApacheWarns, does nothing

Inside a <Directory> block Apache refuses the server-scope rows (GeneratedFilePrefix, InheritVHostConfig, FetchFromModSpdy, NumShards and UrlPrefix); put them at server level or in a <VirtualHost>, or delete them.

All but ShardDomain are accepted and then ignored. ShardDomain still shards, and its warning says why you should stop: sharding hurts with HTTP/2 and HTTP/3. Remove the lines when you can; none needs a replacement.

On nginx, seven of these names (FileCacheCleanIntervalMs, FileCacheInodeLimit, DistributeFetches, DistributedRewriteKey, DistributedRewriteServers, DistributedRewriteTimeoutMs and MaxPrefetchJsElements) are accepted with a warning from 2.9.0 on. Earlier releases do not recognize them, and nginx -t fails until you delete the lines.

Changed defaults

Four defaults differ from 1.14. A configuration that sets the value explicitly is unaffected; check the ones you leave unset.

  • NumRewriteThreads and NumExpensiveRewriteThreads: were 4 when the server is threaded and 1 otherwise; the unset default now follows the CPU budget and the number of server processes.
  • FileCacheSizeKb: was 100 MB, now 1 GB.
  • GoogleFontCssInlineMaxBytes: was 3 KiB, now 48 KiB.

Settings to check after upgrading

  • ExperimentSpec. An ExperimentSpec in the main configuration that sets options above directory scope now fails at load; set such options outside the ExperimentSpec. ExperimentSpec options= accepts only options that can be set per directory; an experiment that names any other option is refused. An ExperimentSpec that sets an alternate origin domain is refused in .htaccess files (500 error) and in remote configuration; set it in the server or virtual-host configuration.
  • Apache .htaccess. Files with MapOriginDomain, MapProxyDomain or CustomFetchHeader now give a 500 error. Move these directives to the server or virtual-host configuration.
  • MapProxyDomain no longer forwards visitor cookies or credentials to the mapped host. If the mapped host relies on receiving them, change that setup before upgrading.
  • In-place optimization and MapProxyDomain: a response fetched for a visitor whose request carried a cookie is shared only when the origin marks it shareable: Cache-Control: public or s-maxage for pages, a stated lifetime (max-age, s-maxage or Expires) for stylesheets, scripts and images. Entries stored by earlier versions on these paths are fetched again once after the upgrade.
  • RequestOptionOverride. If you set it, rotate the token after upgrading.
  • IIS RequestOptionOverride. Do not send the token in a response header: IIS does not read it from responses, and web.config customHeaders send it to every client. If it was ever set there, choose a new token.
  • ASP.NET Core. On a cache miss, the page is re-fetched anonymously, so each cached response is requested twice. Set RecordResponses to false if your GET handlers have side effects; put rules that admit clients by address or identity after UsePageSpeed(), or list their paths in ExcludePaths; and call UseRouting() after UsePageSpeed().

Security updates

Security fixes ship as regular releases through the channel you installed from, and every one is listed under Security in the release notes by impact class, with “update recommended” and the affected versions. The signed packages are free for everyone. A support subscription adds support from the people who build the product, with first-response targets and advance notice of planned security releases. Security fixes reach everyone at the same time. Every release from 2.6.0 on carries its SPDX SBOM and VEX document, and both are also in the source tree.

Roll back

Roll the module and the optimizer back together, optimizer first, to the previous release you ran. After a release that changed the cache format, the previous release’s cache files are still on disk, so the rollback starts with a warm cache (on nginx, only until you ran the one-time flush that release asked for). Uninstall and rollback has the commands per shape.

Frequently asked questions

Do I upgrade the module and the optimizer worker separately?

No. They are a matched pair: install, upgrade and roll them back together, and start the optimizer before the web server. On the packages the Apache module depends on the worker package at the same version, so one upgrade command moves both.

How do security updates reach me?

As regular releases through the channel you installed from, listed under Security in the release notes by impact class with “update recommended”. Security fixes reach everyone at the same time. A support subscription adds first-response targets and advance notice of planned security releases. Every release from 2.6.0 on carries its SPDX SBOM and VEX document, and both are also in the source tree.

Search