ngx_cache_purge

An NGINX module for removing entries from FastCGI, proxy, SCGI and uWSGI caches. In v4, generation keys can stop new requests from using old entries before their files are deleted. REFRESH can ask a proxy origin whether cached content has changed. Both features require explicit configuration. Existing PURGE syntax remains available, but HTTP responses change; see migration.

Português (Brasil) · Español · Русский · Français · 한국어 · Türkçe · Bahasa Indonesia · 简体中文 · Deutsch · 日本語 · Polski · Tiếng Việt · Українська · فارسی

---

Contents

• Features
• Compatibility
• Distribution packages
• Installation
• Usage
• Configuration examples
• REFRESH reference
• Security
• Migration
• Documentation
• See also
• Sponsors
• License

Features

• Inline purge — dedicated HTTP method (PURGE) with IP-based access control.
• Separate purge location — proxy_cache_purge zone key handles captured keys without requiring proxy_pass in the purge location.
• Partial-key purge — a trailing * selects matching cache entries.
• purge_all — purge every entry in a cache zone with one request.
• Background queue — defer filesystem walks to bounded event-loop steps or an optional NGINX thread pool, with configurable batching and throttling.
• Vary-aware purge — remove cached variants for an exact key, including gzip and Vary variants.
• Response formats — json (default), html, xml, text and none.
• Named pools — select a pool with incremental execution when threads are unavailable or on Windows.
• Active-work deduplication — coalesce duplicate purge requests during a walk with at most one pending replay.
• Status metrics — per-cache queue, deletion and HIT/MISS statistics.
• Generation keys — invalidate exact keys, prefixes or namespaces without synchronous deletion; late writes to old generations remain unreachable.
• REFRESH — check cached proxy content against the origin without prewarming it. See REFRESH.

Compatibility

Use a maintained NGINX release for production. POSIX/UNIX is the primary target; Windows is experimental. Threads are optional: without --with-threads, background walks run in small event-loop steps. See the tested versions and platforms.

Distribution packages

Several distributions and ports projects package this fork, but their builds may use older versions rather than v4. Check the package version and NGINX ABI before installing. See the distribution packages and sources.

Installation

cd /path/to/nginx-source
./configure --add-module=/path/to/ngx_cache_purge
make
make install

Dynamic module:

./configure --with-compat --add-dynamic-module=/path/to/ngx_cache_purge
make modules

Use matching NGINX sources; --with-compat does not provide compatibility across arbitrary NGINX versions or C libraries. See dynamic modules and release archives.

Usage

Start with the inline PURGE example, then choose the behavior that matches your cache invalidation requirements. The configuration examples cover separate purge locations, background cleanup, full-cache purge, response formats and Vary-aware removal.

For v4 generation-key invalidation and conditional REFRESH, follow the complete product catalog example.

For a comparison of PURGE, background cleanup, generation keys and REFRESH, see choosing a cache operation.

A trailing * selects matching cache keys. See partial-key PURGE for key-size limits, case sensitivity and selector rules.

Generation keys prevent new requests from reaching invalidated entries, including stale files written by older in-flight requests. See generation-key operation for namespace persistence and cleanup constraints.

REFRESH checks cached proxy content against the origin without refilling or extending its TTL. See REFRESH semantics and limits.

Security

• Restrict purge endpoints with allow / deny directives or an upstream authentication layer. Never expose them publicly.
• Set cache_purge_queue_size to a value appropriate for your traffic to limit shared memory consumption under request floods.
• Consider pairing purge locations with limit_req to rate-limit purge requests independently of normal traffic.

Migration

v4 defaults to JSON and returns 200 no_match for a missing entry. cache_purge_legacy_status only warns and no longer changes responses. Update clients and perform a full restart when upgrading from a different shared-memory layout. Generation keys are opt-in and change cache filenames. See migration details.

Documentation

• Directive reference
• More configuration examples
• Operations and troubleshooting
• HTTP results and REFRESH limits
• Migration to v4
• Implementation architecture
• Development and tests

See also

• ngx_slowfs_cache
• nginx-selective-cache-purge-module
• nginx documentation

Sponsors

We thank the following organizations for providing tools and services free of charge to support the development and maintenance of ngx_cache_purge as an open-source project:

• PVS-Studio - static code analyzer for Enterprise (C, C++, C#, Go, and Java) and Web (JS and TS) development.

License

Copyright (c) 2009-2014, FRiCKLE <info@frickle.com>
Copyright (c) 2009-2014, Piotr Sikora <piotr.sikora@frickle.com>
Copyright (C) 2016-2026, Denys Denysov

Redistribution and use in source and binary forms, with or without
modification, are permitted provided that the following conditions
are met:

1. Redistributions of source code must retain the above copyright
   notice, this list of conditions and the following disclaimer.
2. Redistributions in binary form must reproduce the above copyright
   notice, this list of conditions and the following disclaimer in
   the documentation and/or other materials provided with the
   distribution.

THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
"AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS
FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE
COPYRIGHT HOLDERS OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT,
INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
(INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED
OF THE POSSIBILITY OF SUCH DAMAGE.