Image
Image
Search our site for answers
Help Docs Performance Website Optimization Using mod_pagespeed with Apache

Using mod_pagespeed with Apache

Learn to install, configure, and use the mod_pagespeed Apache module to automatically optimize your website, improving speed and user experience.
Performance
10 min read

Mod_pagespeed is an open-source Apache module, created by Google, that automatically applies web performance best practices to your websites. It can help reduce latency and bandwidth usage by rewriting web pages and optimizing assets like images, CSS, and JavaScript. This guide will walk you through installing, configuring, and using mod_pagespeed with your Apache web server.

What is mod_pagespeed?

mod_pagespeed intercepts content as it’s served by Apache and optimizes it before sending it to the user’s browser. It employs a variety of “filters” that each perform specific optimization tasks. These can range from compressing images and minifying HTML, CSS, and JavaScript to more advanced techniques like inlining small resources, deferring the loading of JavaScript and images, and extending the cache lifetime of resources.

By automating these optimizations, mod_pagespeed can significantly improve your website’s loading speed and overall user experience, often without requiring changes to your existing content or workflow.

Installation

The method for installing mod_pagespeed can vary depending on your server’s operating system and whether you are using a control panel like cPanel/WHM.

Google provides pre-compiled packages for various Linux distributions.

For Debian/Ubuntu systems:

First, download the appropriate .deb package from the official PageSpeed download page. Choose the 64-bit version unless you have a specific reason to use the 32-bit version.

wget https://dl-ssl.google.com/dl/linux/direct/mod-pagespeed-stable_current_amd64.deb

Then, install the package using dpkg and resolve any dependencies:

sudo dpkg -i mod-pagespeed-stable_current_amd64.deb
sudo apt-get -f install

For CentOS/RHEL systems:

First, download the appropriate .rpm package from the official PageSpeed download page. Choose the 64-bit version.

wget https://dl-ssl.google.com/dl/linux/direct/mod-pagespeed-stable_current_x86_64.rpm

Then, install the package using yum or dnf (for newer RHEL/CentOS versions). You might need to install `at` if it’s not already present:

sudo yum install at  # Or: sudo dnf install at
sudo rpm -U mod-pagespeed-stable_current_x86_64.rpm

Installing these packages typically adds the Google repository to your system, which allows mod_pagespeed to be updated automatically with system updates.

Installation via cPanel/WHM

If your server uses cPanel/WHM, you can usually install mod_pagespeed through EasyApache 4:

  1. Log into WHM as the ‘root’ user.
  2. Navigate to Home > Software > EasyApache 4.
  3. In the “Currently Installed Packages” section, click Customize.
  4. Click on the Apache Modules tab.
  5. In the search box, type “pagespeed”.
  6. Toggle the installation switch for “mod_pagespeed”.
  7. Click Review.
  8. Review the changes and click Provision.

Alternatively, on cPanel servers, you might be able to install it via the command line (as root):

For RHEL 6/7 based systems (like CentOS 6/7):

yum install ea-apache24-mod_pagespeed

For RHEL 8+ based systems (like AlmaLinux 8, Rocky Linux 8):

dnf install ea-apache24-mod_pagespeed

Restart Apache

After installation, you’ll need to restart Apache for the module to be loaded:

For Debian/Ubuntu:

sudo systemctl restart apache2

For CentOS/RHEL:

sudo systemctl restart httpd

If you are using cPanel, the restart usually happens automatically after provisioning in EasyApache, or you can restart via WHM’s “Restart Services” or the command /scripts/restartsrv_httpd.

Configuration

mod_pagespeed is generally configured via files loaded by Apache. The main configuration file is typically named pagespeed.conf. Its location can vary:

  • Debian/Ubuntu: /etc/apache2/mods-available/pagespeed.conf (symlinked to mods-enabled)
  • CentOS/RHEL: /etc/httpd/conf.d/pagespeed.conf
  • cPanel/EasyApache: Often found in a path like /etc/apache2/conf.modules.d/XYZ_pagespeed.conf (where XYZ is a number) or within the EasyApache configuration structure.

By default, mod_pagespeed is turned on with a conservative set of filters known as the “CoreFilters”.

Turning mod_pagespeed on or off

You can control whether mod_pagespeed is active using the ModPagespeed directive in your pagespeed.conf file or within a virtual host configuration (or even an .htaccess file if AllowOverride is configured appropriately).

To turn mod_pagespeed on:

ModPagespeed on

To turn mod_pagespeed off (it will still process the HTML but won’t make changes):

ModPagespeed off

To completely disable mod_pagespeed so it doesn’t even parse the page (useful for troubleshooting):

ModPagespeed unplugged

Note: The unplugged value can typically only be used in the top-level Apache configuration or virtual hosts, not in .htaccess files.

Configuring filters

mod_pagespeed has over 40 different optimization filters. You can enable or disable specific filters to fine-tune its behavior.

To enable additional filters:

ModPagespeedEnableFilters filter_name1,filter_name2

For example, to enable combining CSS files and extending cache for CSS:

ModPagespeedEnableFilters combine_css,extend_cache_css

To disable filters that are part of the CoreFilters set or enabled by default:

ModPagespeedDisableFilters filter_name1,filter_name2

You can also set different “Rewrite Levels”. The default is CoreFilters. Another option is PassThrough, which disables all filters except those you explicitly enable.

ModPagespeedRewriteLevel PassThrough
ModPagespeedEnableFilters rewrite_images,collapse_whitespace

A full list of available filters and their descriptions can be found on the official PageSpeed Filters documentation.

File cache configuration

mod_pagespeed needs a directory to cache optimized files. This is typically configured automatically during installation. Important directives include:

  • ModPagespeedFileCachePath: Specifies the directory for the cache. Ensure Apache has write permissions to this directory. Example: ModPagespeedFileCachePath "/var/cache/mod_pagespeed/"
  • ModPagespeedFileCacheSizeKb: Sets the maximum size of the file cache in kilobytes.
  • ModPagespeedFileCacheCleanIntervalMs: How often, in milliseconds, the cache should be cleaned.
  • ModPagespeedFileCacheInodeLimit: Maximum number of inodes the cache can use.

Handling HTTPS resources

If your website serves resources over HTTPS that mod_pagespeed needs to fetch and optimize (e.g., CSS or JavaScript files on a different HTTPS domain, or even on the same domain if Apache isn’t configured to see the unencrypted traffic), you may need to enable HTTPS fetching:

ModPagespeedFetchHttps enable

In some cases, particularly with self-signed certificates or specific SSL configurations, you might need additional options:

ModPagespeedFetchHttps enable,allow_self_signed,allow_unknown_certificate_authority

Always ensure this is necessary and understand the security implications before allowing less strict SSL certificate validation.

Verifying mod_pagespeed

Once installed and configured, you can verify if mod_pagespeed is working by inspecting the HTTP response headers of your website. You can use your browser’s developer tools or a command-line tool like curl.

curl -I http://yourdomain.com

Look for an X-Mod-Pagespeed header. Its presence indicates that mod_pagespeed is active. The value of the header usually indicates the version of mod_pagespeed being used.

HTTP/1.1 200 OK
Date: Fri, 30 May 2025 15:00:00 GMT
Server: Apache
X-Mod-Pagespeed: 1.13.35.2-0
Content-Type: text/html; charset=UTF-8
...

You can also view the source code of your web pages. You should see changes made by mod_pagespeed, such as minified HTML, optimized image URLs (often containing .pagespeed. in the filename), or combined/inlined CSS/JavaScript.

Common filters and best practices

  • Start with CoreFilters: The default CoreFilters rewrite level provides a good balance of performance improvements and safety.
  • Image Optimization: Filters like rewrite_images (which encompasses several sub-filters like recompress_images, convert_jpeg_to_progressive, resize_images) are highly effective. Ensure your images have dimensions specified in <img> tags or CSS for optimal resizing.
  • CSS & JavaScript Minification/Concatenation: Filters like combine_css, rewrite_css, combine_javascript, and rewrite_javascript can reduce the number of requests and the size of these assets.
  • Leverage Browser Caching: extend_cache helps instruct browsers to cache resources for longer periods.
  • Test Thoroughly: Some filters, especially more aggressive ones, can occasionally cause issues with certain websites or JavaScript functionalities. Always test your website thoroughly after enabling new filters. You can disable mod_pagespeed for specific URLs or directories if needed, or disable problematic filters.
  • Monitor Performance: Use web performance testing tools to measure the impact of mod_pagespeed and adjust your configuration accordingly.
  • Respect Vary Headers: If your site uses Vary headers (e.g., Vary: User-Agent) for legitimate reasons, you might need to configure ModPagespeedRespectVary on.
  • Don’t Double Optimize: If you are already using other tools or CDNs that perform similar optimizations, ensure they don’t conflict with mod_pagespeed.

Troubleshooting

  • Check Apache Error Logs: This is the first place to look for issues. The logs are typically located at /var/log/apache2/error.log (Debian/Ubuntu) or /var/log/httpd/error_log (CentOS/RHEL). Look for messages containing “pagespeed”.
  • No X-Mod-Pagespeed Header:
    • Ensure the module is loaded (check your Apache configuration).
    • Verify ModPagespeed on is set in the correct scope.
    • Check for conflicting SetOutputFilter directives in your Apache configuration.
  • Broken Site or Functionality:
    • Try disabling mod_pagespeed temporarily using the query parameter: http://yourdomain.com/?ModPagespeed=off. If this fixes the issue, mod_pagespeed is likely the cause.
    • If ModPagespeed=off works, try http://yourdomain.com/?ModPagespeed=on&ModPagespeedFilters= (this enables PageSpeed but with no filters). If the site is broken now, it might be an HTML parsing issue with PageSpeed itself.
    • If the above works, then a specific filter is likely causing the problem. You can try disabling filters one by one or groups of filters in your pagespeed.conf until the issue is resolved. The CoreFilters set is generally safe, but custom-added filters might be more aggressive.
  • Resources Not Being Optimized:
    • Cacheability: mod_pagespeed typically won’t optimize resources with Cache-Control: no-cache, private, or no-transform headers unless configured otherwise (e.g., ModPagespeedDisableRewriteOnNoTransform off).
    • Cross-Domain Resources: If CSS, JavaScript, or images are served from a different domain, you need to authorize that domain using ModPagespeedDomain.
    • HTTPS Fetching: As mentioned earlier, ensure ModPagespeedFetchHttps enable is set if resources are on HTTPS.
    • File Permissions: Ensure the Apache user can write to the ModPagespeedFileCachePath.
  • Clearing the Cache: Sometimes, clearing the mod_pagespeed cache can resolve issues. You can do this by stopping Apache, removing the contents of the ModPagespeedFileCachePath, and then starting Apache. sudo systemctl stop apache2 # or httpd sudo rm -rf /var/cache/mod_pagespeed/* sudo systemctl start apache2 # or httpd Alternatively, you can touch a `cache.flush` file in the cache directory: sudo touch /var/cache/mod_pagespeed/cache.flush This signals mod_pagespeed to purge its cache. (The exact path might differ based on your ModPagespeedFileCachePath setting).

Uninstalling mod_pagespeed

If you need to remove mod_pagespeed:

For Debian/Ubuntu systems:

sudo apt-get remove mod-pagespeed-stable
sudo apt-get autoremove # To remove unused dependencies

For CentOS/RHEL systems:

sudo yum remove mod-pagespeed-stable

For cPanel/WHM (using EasyApache 4):

  1. Log into WHM as the ‘root’ user.
  2. Navigate to Home > Software > EasyApache 4.
  3. In the “Currently Installed Packages” section, click Customize.
  4. Click on the Apache Modules tab.
  5. Search for “pagespeed”.
  6. Toggle the switch to uninstall “mod_pagespeed”.
  7. Click Review and then Provision.

Or via command line for cPanel/EasyApache:

yum remove ea-apache24-mod_pagespeed # Or dnf remove ...

After uninstallation, remove any custom mod_pagespeed configuration files (like pagespeed.conf if not removed by the package manager) and restart Apache.

sudo systemctl restart apache2 # or httpd

You might also want to remove the cache directory (e.g., /var/cache/mod_pagespeed/).

mod_pagespeed can be a powerful tool for improving your website’s performance. By understanding its configuration options and testing its impact, you can leverage its capabilities to provide a faster experience for your users.

Was this article helpful?