Caching

Cyclone Cache

mod_pagespeed 1.1 replaces the open-source file-based cache with Cyclone Cache. This is the default backend — no configuration change is required when upgrading.

Cyclone Cache stores all cached data in a single fixed-size file. This eliminates the runaway disk usage and millions-of-small-files problem of the old cache.

Key properties:

• Fixed-size cache file — the cache never grows beyond the configured size. When it fills, the least-recently-used entries are evicted automatically.
• Lock-free reads — concurrent requests read from the cache without blocking each other.
• Memory-mapped I/O — the operating system manages which parts of the cache file are held in RAM. Frequently accessed entries stay in memory without a separate in-process cache layer.
• Shared across processes — nginx worker processes and Apache prefork children all share the same cache file. No duplication, no coordination overhead.

Configuration

The FileCachePath directive is accepted for compatibility, but Cyclone Cache uses its own storage location within that directory. Set the path and size:

pagespeed FileCachePath /var/cache/pagespeed;
pagespeed FileCacheSizeKb 2097152;

ModPagespeedFileCachePath /var/cache/pagespeed
ModPagespeedFileCacheSizeKb 2097152

pagespeed FileCachePath %ProgramData%\We-Amp\IISWebSpeed\Cache
pagespeed FileCacheSizeKb 2097152

The default cache size is sufficient for most sites. See Cache sizing below for guidance on larger deployments.

LRU cache

Each process maintains a small in-memory LRU (least recently used) cache for metadata. This avoids repeated lookups for small, frequently accessed items such as HTTP response headers and rewrite metadata.

LRUCacheKbPerProcess controls the total size of the in-memory cache per process. LRUCacheByteLimit controls the maximum size of a single entry — items larger than this limit bypass the LRU cache and go directly to the on-disk cache.

pagespeed LRUCacheKbPerProcess 2048;
pagespeed LRUCacheByteLimit 32768;

ModPagespeedLRUCacheKbPerProcess 2048
ModPagespeedLRUCacheByteLimit 32768

pagespeed LRUCacheKbPerProcess 2048
pagespeed LRUCacheByteLimit 32768

When the LRU cache reaches its size limit, it evicts entries down to 75% of the limit — not to zero.

Shared memory metadata cache

The shared memory metadata cache allows all processes on a server to share small metadata (response headers, cache invalidation records) through a shared memory segment. This avoids each process maintaining its own copy and reduces disk lookups.

pagespeed DefaultSharedMemoryCacheKB 100000;

ModPagespeedDefaultSharedMemoryCacheKB 100000

pagespeed DefaultSharedMemoryCacheKB 100000

The shared memory cache checkpoints its contents to disk periodically. On restart, mod_pagespeed reloads the checkpoint so the cache is warm immediately rather than starting empty.

Two virtual hosts that share the same FileCachePath also share the same shared memory cache segment.

External caches

mod_pagespeed 1.1 supports memcached and Redis as external cache backends. These are useful when multiple servers need to share cached resources.

You cannot use both memcached and Redis for the same virtual host. Pick one.

Memcached

Point mod_pagespeed at one or more memcached servers:

pagespeed MemcachedServers "cache1.example.com:11211,cache2.example.com:11211";
pagespeed MemcachedTimeoutUs 500000;

ModPagespeedMemcachedServers "cache1.example.com:11211,cache2.example.com:11211"
ModPagespeedMemcachedTimeoutUs 500000

pagespeed MemcachedServers 127.0.0.1:11211
pagespeed MemcachedTimeoutUs 500000

"C:\memcached\memcached.exe" -m 256 -d runservice

Health checking: if a memcached server exceeds 4 timeouts within 30 seconds, mod_pagespeed stops performing optimization for 30 seconds rather than blocking requests on a slow cache.

Redis

Point mod_pagespeed at a Redis server:

pagespeed RedisServer "cache.example.com:6379";
pagespeed RedisTimeoutUs 50000;

ModPagespeedRedisServer "cache.example.com:6379"
ModPagespeedRedisTimeoutUs 50000

pagespeed RedisServer "cache.example.com:6379"
pagespeed RedisTimeoutUs 50000

RedisDatabaseIndex selects a specific Redis database. This directive is incompatible with Redis clustering, which does not support database selection.

RedisTTLSec sets a TTL on all cache entries. The default of -1 means entries do not expire in Redis (mod_pagespeed manages its own expiration logic). Set a positive value if you need Redis to reclaim memory independently.

Cache flushing and purging

Flush the entire cache

Touch a cache.flush file in the cache directory to force mod_pagespeed to discard all cached data:

sudo touch /var/cache/pagespeed/cache.flush

mod_pagespeed checks for this file periodically. All entries cached before the file’s modification time are treated as expired.

Purge via admin page

Send a purge request through the built-in admin interface:

# Purge everything
curl 'http://example.com/pagespeed_admin/cache?purge=*'

# Purge a specific URL
curl 'http://example.com/pagespeed_admin/cache?purge=http://example.com/style.css'

# Purge with a wildcard
curl 'http://example.com/pagespeed_admin/cache?purge=http://example.com/images/*'

Purge via HTTP PURGE method

When EnableCachePurge is on, mod_pagespeed accepts standard HTTP PURGE requests:

pagespeed EnableCachePurge on;

ModPagespeedEnableCachePurge on

pagespeed EnableCachePurge on

Then purge by URL:

curl -X PURGE http://example.com/style.css

Multi-server deployments

Cache purge and flush operations apply only to the server that receives the request. In a multi-server deployment, run the purge on every server independently. mod_pagespeed does not propagate purge requests across servers.

Cache sizing

Size the Cyclone Cache file at 3 to 4 times the total size of your original (unoptimized) assets. mod_pagespeed stores variants alongside the originals, so the cache needs space for both.

For example, if your site serves 500 MB of images, CSS, and JavaScript, set the cache to 1.5-2 GB.

The LRU cache evicts entries down to 75% of its configured limit when full — it does not empty completely on eviction.

In-Place Resource Optimization (IPRO)

IPRO optimizes resources served from your origin without changing their URLs. This is useful for resources referenced by third-party code or cached at CDN edge nodes where you cannot change the URL.

IPRO is on by default.

pagespeed InPlaceResourceOptimization on;
pagespeed InPlaceSMaxAgeSec 10;

ModPagespeedInPlaceResourceOptimization on
ModPagespeedInPlaceSMaxAgeSec 10

pagespeed InPlaceResourceOptimization on
pagespeed InPlaceSMaxAgeSec 10

InPlaceSMaxAgeSec controls how long the optimized resource is considered fresh before mod_pagespeed checks the origin again. Keep this low (the default of 10 seconds is appropriate for most sites) to ensure changes propagate quickly.

Considerations when using IPRO:

• Resources keep their original URLs, so they do not benefit from content-hash-based cache extension. Browser caches and CDNs follow the original Cache-Control headers.
• IPRO cannot combine resources (CSS combining, JS combining) because each resource retains its own URL.

Fetch and performance

These directives control how mod_pagespeed fetches resources from your origin and how long it spends optimizing them per request.

pagespeed FetcherTimeoutMs 10000;
pagespeed RewriteDeadlinePerFlushMs 20;
pagespeed ImplicitCacheTtlMs 600000;
pagespeed FetchWithGzip on;
pagespeed HttpCacheCompressionLevel 6;

ModPagespeedFetcherTimeoutMs 10000
ModPagespeedRewriteDeadlinePerFlushMs 20
ModPagespeedImplicitCacheTtlMs 600000
ModPagespeedFetchWithGzip on
ModPagespeedHttpCacheCompressionLevel 6

pagespeed FetcherTimeoutMs 10000
pagespeed RewriteDeadlinePerFlushMs 20
pagespeed ImplicitCacheTtlMs 600000
pagespeed FetchWithGzip on
pagespeed HttpCacheCompressionLevel 6