--- title: "Using mod_pagespeed with Apache" source: "https://docs.nexcess.com/hosting/performance/website-optimization/using-mod_pagespeed-with-apache/" description: "Learn to install, configure, and use the mod_pagespeed Apache module to automatically optimize your website, improving speed and user experience." vertical: "Hosting" date: "2025-05-30" last_modified: "2026-07-30" --- # Using mod_pagespeed with Apache `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. ### Command line installation (recommended for non-cPanel servers) 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](https://www.modpagespeed.com/doc/download). 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](https://www.modpagespeed.com/doc/download). 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](https://www.modpagespeed.com/doc/filters). ### 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 `` 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.