Nginx Cache Purge Preload

Yes. NPP is designed exclusively for Nginx web servers running on Linux. It does not work on Apache, shared hosting, or environments where shell_exec and exec are disabled.

No. The ngx_cache_purge module is optional. When available, NPP uses it as the fastest purge path (HTTP Purge). If it is not present, NPP automatically falls back to a URL index lookup and then a full filesystem scan. Nothing breaks either way.

Mostly basic, built-in shell tools are required. wget is required for cache preloading. For hardened shell execution, safexec is highly recommended — see the Help tab for installation instructions. For large cache-heavy websites, especially when Nginx cache paths are located on FUSE-based mounts (such as bindfs to solve permission issues), ripgrep (rg) is strongly recommended for significantly faster cache purge performance.

The most common reasons are: shell_exec and exec is disabled, open_basedir restrictions prevent required filesystem access, the PHP-FPM user lacks write permission to the Nginx cache directory, or automatic Nginx detection fails (for example, nginx.conf cannot be located). See the Help tab for a full environment checklist and solutions.

This is the most common issue in environments where the WEBSERVER-USER (nginx/www-data) and PHP-FPM-USER are different. NPP provides a one-liner bash script to automate the fix using bindfs on monolithic servers. For containerized environments, users can review the full configuration setup via NPP Containerized See the Help tab → Permission Issues section or the GitHub repository for details.

Yes. NPP has built-in Cloudflare APO Sync that mirrors every purge to Cloudflare’s edge cache automatically. Requires the official Cloudflare WordPress plugin. Enable it under Settings.

Yes. NPP supports Redis Object Cache Sync, which keeps Redis and the Nginx cache aligned during purge and preload operations. When enabled, NPP flushes the Redis object cache at the correct point in the Nginx Purge + Preload chain to ensure fresh content is used when rebuilding cache. Enable it under Settings.

Yes. NPP includes built-in WooCommerce Auto-Purge for stock changes and order events, and supports purging the Shop page as a related URL when a product is updated.

Yes, but disable page caching in other plugins to avoid conflicts. You can keep their frontend optimization features (minification, lazy loading, CDN) active. See the Help tab for details.

NPP restricts cache paths by default to prevent accidental deletion of system files. Allowed roots are /dev/shm/, /tmp/, /var/, and /cache/. The path must be at least one level deep (e.g. /var/cache/nginx). These restrictions can be completely disabled using the Bypass Path Restriction feature, which removes all path safety guardrails and allows any directory to be used as the Nginx cache path. Full details in the Help tab.

Yes. NPP includes full WP-CLI integration. You can purge, preload, check status, view logs, update settings, flush transients, and manage scheduled events directly from the terminal — no admin dashboard access required. Run wp help npp and wp help npp <subcommand> to see all available commands.

NPP supports FastCGI, Proxy, SCGI, and UWSGI cache methods. The plugin automatically applies the appropriate purge strategy (HTTP Purge, INDEX Purge, or RG Purge).

HTTP Purge is an optional fast‑path that uses Nginx's ngx_cache_purge module to delete cache entries via a simple HTTP request. It is the fastest possible single‑URL purge method because it avoids any filesystem scan.

RG Purge is a lightning‑fast alternative to the traditional PHP filesystem scan. It uses ripgrep (rg) — line-oriented search tool written in Rust — to locate nginx cache files in a fraction of the time. In a standard Nginx cache with thousands of URLs, the built‑in PHP recursive iterator can take 10–60 seconds to find all cache entries for a single page purge. RG Purge reduces this to 1–2 seconds regardless of cache size by using parallel directory traversal and memory‑mapped I/O. When to enable: large sites over 10.000 URL.

During every cache preload, NPP quietly builds a persistent URL‑to‑filepath index. When you later purge a specific page (manually, or via auto‑purge), the plugin first checks this index. If the URL is found, NPP instantly knows the exact cache file location and deletes it immediately — with zero disk scanning. This is the second‑fastest purge path (FP2) and works even on sites with hundreds of thousands of cached files. The index is automatically updated after each purge and can be cleared manually from the Status tab if your cache structure changes.

safexec is a small, privilege‑dropping wrapper (written in C) created specifically for NPP. It is used to safely execute system commands like wget, and rg while enforcing strict security controls. What it does:

• Drops privileges to a low‑privilege user (nobody) before running the shell command.
• Scrubs the environment to prevent information leaks.
• Optionally normalizes percent‑encoded characters in URLs during cache preloading — solving a common cause of duplicate cache entries (e.g., %2F vs /). Without safexec, the plugin runs commands with the same permissions as the PHP process. safexec adds an extra layer of isolation and is especially valuable:
• Where you want to limit the impact of shell operations (injections).
• In FUSE environments where the PHP user lacks access to the underlying cache directory — safexec can temporarily assume the Nginx user's identity to read directly from the real path. URL Normalization modes: In Preload Settings you can choose how safexec handles percent‑encoded URLs:
• OFF – No normalization (default).
• UPPER – Convert all percent‑encoded sequences to uppercase (e.g., %2f → %2F).
• LOWER – Convert to lowercase.
• PRESERVE – Keep original casing but still normalize unreserved characters. This is crucial if your Nginx $request_uri cache key treats different entries, which can lead to cache fragmentation. Choose the mode that matches your Nginx configuration.

Yes. NPP's preload engine no blindly ignores all query‑string URLs. It uses a smart list of unsafe parameters (cart, checkout, admin, preview, etc.) and allows everything else — sorting options, product filters, language switches, UTM marketing tags — to be preloaded and served from cache. This dramatically increases cache coverage for WooCommerce stores and busy content sites.

Yes. When Auto Purge is enabled and Auto Preload is switched on (globally or per‑page), NPP will immediately begin preloading the affected pages after a purge — no manual steps required. This keeps the cache warm even after content updates, stock changes, or theme/plugin upgrades.

Yes. NPP includes a "Preload Feeds" option that warms your main RSS2, Atom, per‑post comment feeds, and taxonomy‑specific feeds (categories, tags, custom taxonomies). This ensures feed readers, RSS‑to‑email services, and search engine crawlers always receive a fast, cached response — without waking up PHP on every refresh.

Most Nginx cache plugins rely on a single purge method — usually a slow, recursive PHP scan of every file in the cache directory, or they require a special Nginx module. NPP uses a layered fast‑path chain that automatically picks the fastest available method for every single‑URL purge, without you needing to configure anything:

1. FP1 – HTTP Purge – If the ngx_cache_purge module is present, NPP instructs Nginx to delete the cache entry via a simple HTTP request. Near‑instant.
2. FP2 – Index Purge – If the URL is already indexed from a previous preload, NPP finds the cache file path in memory — zero disk scanning.
3. FP3 – RG Purge – If ripgrep is installed, a single, highly optimized system command locates all matching cache files in 1–2 seconds, even on directories with 50,000+ files.
4. FP4 – PHP recursive scan – The traditional method; used only as a silent fallback when nothing faster is available.

• No single point of failure — if one method isn’t available, the next one takes over automatically.
• Your purges are always as fast as your server environment allows, without changing any settings.
• You can improve purge speed later simply by installing ripgrep or enabling the Nginx module — the plugin adapts instantly. No other Nginx cache plugin offers this kind of resilient, self‑optimizing purge stack. It is one of the key reasons NPP stays fast and safe even on massive WooCommerce sites, and high‑traffic news platforms.