Getting started with Caching Out

Version covered: 1.25.0.

1. What Caching Out does

Caching Out keeps a ready-made copy of each page and serves that copy to anonymous visitors before WordPress loads. It writes browser caching and compression rules into your server configuration, loads images, iframes and video as they are needed rather than all at once, and can minify your CSS and JavaScript. It rebuilds the copies when your content changes. It is designed to improve LCP, INP and CLS.

The plugin is fast by default and tunable on demand. Page caching, purging, browser caching, compression and lazy loading are on the moment you activate, with no configuration. Anything that can change how a page looks stays off until you switch it on. Caching Out Pro is a separate add-on you install alongside the free plugin; it adds CSS and JavaScript delivery work, Unused CSS/JS, cache preloading, the Activity record, Performance Insights, CDN rewriting, WP-CLI and more. The free plugin is complete on its own and keeps running exactly as before if you remove Pro.

Performance results vary depending on hosting, theme, plugins and traffic. Benchmark figures are measured on our published test suite and are not a guarantee of results on any specific site.

2. Requirements

Supported servers:

• Apache. Full support. The browser caching and compression rules are written into .htaccess automatically.
• LiteSpeed. Treated as Apache. The same .htaccess rules are written.
• NGINX. Page caching works unchanged. NGINX does not read .htaccess, so the browser caching and compression rules must be added to your server block by hand, once. The snippet is in server-config.md.
• IIS. Page caching works. IIS uses web.config, which Caching Out does not write; browser caching and compression are configured in IIS by you or your host. See server-config.md.

Licences apply to the free plugin's Pro add-on only. Every paid tier unlocks the same features; the tiers differ in how many sites they cover and how long support runs:

A zero-cost developer tier is issued automatically for local and staging domains. See Licensing.

3. Before you install

Deactivate and delete any other page-cache plugin first.

WordPress allows only one page-cache drop-in, the file wp-content/advanced-cache.php. Caching Out records a fingerprint of the drop-in it writes and checks it before every write. If the file on disk is not the one Caching Out wrote, it leaves that file alone, does not switch page caching on, and shows a notice naming the plugin the file belongs to. Every other part of the plugin keeps working, but you will not get a page cache until the other plugin's drop-in is gone.

The same rule covers .htaccess. Caching Out refuses to write its browser caching rules while another caching plugin's marker block still carries live rules, and it never writes into or removes another plugin's block.

Removing a caching plugin often leaves files behind. After you activate Caching Out, open Caching Out > Filesystem Check. It lists leftovers from removed cache plugins – stale folders, config files, and empty or still-active .htaccess marker blocks – with the exact path and whether each is safe to delete. Caching Out never deletes another plugin's files for you.

4. Install the free plugin

1. In wp-admin, go to Plugins > Add New, search for Caching Out, and click Install Now. Or download the zip, click Upload Plugin, choose the file and install it. You can also upload the folder to /wp-content/plugins/cachingout over FTP.
2. Click Activate.

Activation does all of this on its own:

• Writes the page-cache drop-in to wp-content/advanced-cache.php, after checking that no other plugin owns it.
• Adds define( 'WP_CACHE', true ); to wp-config.php, taking a backup first and refusing to write if the result fails a sanity check. This step is skipped when a foreign drop-in was found.
• Removes any stale Caching Out rewrite block left in .htaccess.
• Schedules the cache expiry task.
• Saves the default settings. Existing settings are never overwritten.
• Writes the browser caching blocks (Expires headers, GZIP and Brotli) to .htaccess, again with a backup first and the foreign-marker guard.
• Clears any stale cached HTML and writes the settings snapshot the drop-in reads.

The activation report. Every one of those steps is recorded and shown in wp-admin as the "Caching Out filesystem check" notice. It lists each step as OK or FAILED with the reason, then the paths it checked and whether each exists. A green notice means every write succeeded. A red one tells you which write failed, which on most hosts is a permissions problem on wp-content/ or wp-config.php. If only the browser caching rules failed, the notice says so plainly: the page cache is still working. The notice carries three buttons: Open Setup Wizard, Settings and Re-run filesystem check.

5. Install the Pro add-on

Pro is not on WordPress.org. The email that brings your licence key after purchase (from support@cachingout.com, subject "Your Caching Out License Key") also carries the download link for the Pro add-on zip. Keep that email: the key is not shown in your account on cachingout.com. If it has not arrived after 15 minutes, check your spam folder, then write to support@cachingout.com from the address you bought with.

1. Make sure the free Caching Out plugin is active and at the same version as Pro. Pro runs only with free Caching Out 1.22.0 or newer; the two are released as a pair. With the free plugin absent or older, Pro registers nothing and shows one notice saying so. Always update the free plugin first.
2. Go to Plugins > Add New > Upload Plugin, choose the cachingout-pro zip and install it.
3. Click Activate.
4. Go to Caching Out > Settings > License, paste your licence key and click Activate.

Until the licence validates, Pro is installed but not switched on. In that state it scans and audits, it lets you configure it, and it changes nothing for your visitors. A notice on the plugin's pages says "Caching Out Pro is installed but not switched on", with buttons to run the scan or enter your licence. The moment the key validates, Pro's features switch on and any settings you already saved apply.

A licence that later lapses never switches anything off. It stops updates and support only, and it never affects the free plugin underneath.

6. The setup wizard

The wizard opens automatically after activation, and is always available at Caching Out > Setup Wizard. Every step can be skipped, and every setting in it can be changed later from the settings tabs.

1. Welcome. What the wizard covers, and a note that the defaults are safe for most sites. Nothing to fill in.
2. Smart Config (Pro only). Detects your plugins and theme and suggests the safest matching settings. Nothing is sent until you click Run scan.
3. Privacy (Pro only). The opt-in for anonymous performance data. The box is unticked and stays unticked unless you tick it.
4. Caching. Turn page caching on or off, set the cache lifespan in hours, and choose whether mobile visitors get their own cache files. The same step carries the browser caching switches: Expires headers, GZIP and Brotli.
5. Media. Lazy loading for images, iframes and CSS background images.
6. File Optimization. Minify CSS, minify JavaScript and defer JavaScript. These change how a page is built, so the step advises turning on one at a time and checking the site after each.
7. Ready! A summary of what is now active, and a link to the settings page.

Skip the wizard entirely if you want the defaults. Activation has already applied them; the wizard only exposes the same switches earlier.

7. Verify it is working

Three checks, in order.

1. View the page source as an anonymous visitor. Open a private or incognito window and load a page on your site. Reload it once. View the source of that second load and look at the very end for a line like:

   <!-- Caching Out - page generated and cached on 2026-09-03 11:42:07 UTC -->
   

   The comment is on the cached copy, so the first visit will not show it: that visit is what generates the file. Logged-in visitors are never served from cache, which is why this check must be done logged out.

2. Check the admin bar. Logged in as an administrator, look for the Caching Out item in the WordPress toolbar. It appears on the front end and in wp-admin.

3. Run the Page Audit. Go to Caching Out > Settings > Insights and click Audit pages now. Caching Out reads each tracked page the way a visitor would and lists what to fix, with a one-click button where a plugin setting answers the finding. It needs no API key.

If a page is not being cached and you want to know why, see troubleshooting.md and Page caching, which explain the X-CachingOut-Cache debug header and its bypass reasons.

8. Daily use

The admin bar. The Caching Out toolbar item holds:

• Purge Cache. Clears every cached page. Available to administrators in both editions.
• Preload Cache. Fetches your own pages so the cache is warm again. This is a Pro feature, so the item appears only while Pro is active and switched on.

The cache purges itself when:

• A post or page is published, updated, trashed or restored. Archives and the pages that list the changed post are purged with it.
• A comment is approved, edited or deleted.
• A term, menu, widget or customizer setting changes.
• The theme is switched.
• A plugin is activated or deactivated.
• A WooCommerce product's stock or price changes. A completed order purges only the purchased products' pages.
• You save a setting that changes what a page outputs.

The Activity screen (Pro) records every change the plugin makes to your settings and your server files: who, when, the value before and after, and whether it succeeded. Settings and rule changes can be reverted with one click. The record stays in your own database and is never sent anywhere on its own. See Activity log.

9. Updating

• The free plugin updates like any WordPress.org plugin: from Dashboard > Updates or the Plugins screen. You can also upload a newer zip over the top; the plugin re-runs its filesystem check after an overwrite without needing a deactivate and activate cycle.
• The Pro add-on updates through the licence server, and only while the licence is valid. An expired licence pauses updates; it does not switch anything off.

Always update the free plugin first. Pro checks the free plugin's version on every request and refuses to run against an older one.

10. Deactivating and uninstalling

Deactivating the free plugin does two things and no more:

• Deletes wp-content/advanced-cache.php, but only when the file still matches the fingerprint Caching Out recorded when it wrote it.
• Clears the plugin's scheduled tasks.

Deactivation never edits .htaccess and never edits wp-config.php. WP_CACHE is left in place, which is harmless: WordPress only loads the drop-in when the file exists.

Deleting the free plugin (Plugins screen, Delete after deactivation) runs the full scrub:

• Removes the drop-in, if it is still ours.
• Deletes wp-content/cache/cachingout/ and everything in it.
• Clears every scheduled task the plugin owns.
• Removes all four Caching Out marker blocks from .htaccess, markers included, after checking the result. The file is replaced in one step: if it cannot be written, it is left exactly as it was.
• Removes the WP_CACHE line from wp-config.php, line by line, the same way. No copy of wp-config.php or .htaccess is ever left on disk.
• Deletes the plugin's options, transients and user meta, on every site of a multisite network.

Nothing is written after that, so the cache folder does not come back. There is no "keep my data" setting and no separate clean-up step to run first: Delete is the whole job.

Deactivating Pro leaves the site running on the free plugin. Every Pro setting keeps its stored value, the cache is purged once so that what visitors get matches the free feature set, and nothing else changes. Reactivating Pro restores everything. Deleting Pro removes its own data, including the Activity table, except the backups of compressed images you have not restored (see step 2 below).

Removing Caching Out completely

1. If you use Pro and want to move your licence to another site, open Caching Out > License and click Deactivate first. Deleting Pro does not free its site on your licence.
2. If you compressed images with Pro and want every original back, open Caching Out > Image compression and click Restore all before you delete Pro. Uninstalling Caching Out Pro removes its compressed copies and records but keeps the backups of any image you have not restored, in wp-content/cachingout-images/backup/; delete that folder yourself once you no longer need it.
3. Deactivate and delete Caching Out Pro, then Caching Out, on the Plugins screen. Delete is what removes the data; deactivating alone deliberately leaves the WP_CACHE line and the .htaccess blocks.
4. Check two files. Both should be clean, but a host can make a file read-only, and then nothing is written to it:
   • .htaccess in your site root: no block starting with # BEGIN WP Caching Out (four names: plain, Expires, GZIP, Brotli). Delete any you find, from its BEGIN line to its END line.
   • wp-config.php: no define( 'WP_CACHE', true ); line under the comment Enable WP Caching Out page cache. Delete both lines.
5. Another caching plugin installed? Deleting Caching Out removes the WP_CACHE line from wp-config.php. If another page-cache plugin is active, save its settings once afterwards so it adds the line back.
6. NGINX: the server block you added by hand from server-config.md stays until you remove it.
7. If you used Caching Out's CDN, Cloudflare or Sucuri add-ons, their own caches and accounts are outside WordPress; purge or close them there.

Removing WebP or AVIF serving deletes nothing in your uploads: WebP / AVIF delivery never creates image files, so copies made by another plugin belong to that plugin. Pro's Image compression is the one feature that writes image files: it replaces the originals you compress (after backing them up) and keeps its copies and backups in wp-content/cachingout-images/ (step 2).

11. Where to go next

Reference documents:

• settings-reference.md – every setting, its default and plain-language guidance.
• troubleshooting.md – the X-CachingOut-Cache header, the kill switch, and common conflicts.
• server-config.md – what is written to .htaccess, and the NGINX snippet to add by hand.
• privacy.md – what each edition sends, what it stores, and how to stop it. The free plugin makes no outbound request of its own; telemetry belongs to Pro and is opt-in with the box unticked.
• compatibility-matrix.md – tested themes, plugins and hosts.

Knowledge base, by feature:

Two constants are worth knowing before you need them. Adding define( 'CACHINGOUT_DISABLE_CACHE', true ); to wp-config.php disables all cache reading and writing, in every version. Adding define( 'CACHINGOUT_DEBUG', true ); makes every response carry the X-CachingOut-Cache header, which names the exact rule behind any bypass.