Nginx Proxy Cache: Configuring proxy_cache_min_uses and proxy_cache_methods

Configuring proxy_cache_methods and proxy_cache_min_uses in Nginx

In Nginx ngx_http_proxy_module, cached responses are saved in files defined by proxy_cache_path. The cache file name is generated by applying the MD5 function to the cache key. A cached response is first written to a temporary file before being renamed. Two directives in this module regulate whether a response is cached based on the request method and request count: proxy_cache_methods and proxy_cache_min_uses.

Restricting Request Methods with proxy_cache_methods

The proxy_cache_methods directive specifies client request methods that qualify for caching. If the client request method is listed in this directive, the response will be cached.

• Syntax: proxy_cache_methods GET | HEAD | POST ...;
• Default: proxy_cache_methods GET HEAD;
• Context: http, server, location
• Version Availability: Appeared in Nginx version 0.7.59.

The documentation notes that GET and HEAD methods are always added to the list, though it is recommended to specify them explicitly. The documentation also references the proxy_no_cache directive for defining conditions where responses are not cached.

Setting Request Count Thresholds with proxy_cache_min_uses

The proxy_cache_min_uses directive sets the number of requests after which the response will be cached.

• Syntax: proxy_cache_min_uses number;
• Default: proxy_cache_min_uses 1;
• Context: http, server, location
• Version Availability: Version introduction is not specified in the supplied documentation excerpt.

By default, proxy_cache_min_uses is set to 1. Setting this to a higher number configures Nginx to cache the response only after that number of requests has occurred.

Documented Directives Summary

Configuration Example

http {
    proxy_cache_path /data/nginx/cache levels=1:2 keys_zone=one:10m;

    # Note: Upstream backend definitions or upstream servers are assumed to be defined elsewhere.
    server {
        listen 80;
        server_name example.com;

        location / {
            proxy_pass http://backend_upstream;
            proxy_cache one;

            # Set the number of requests after which the response will be cached
            proxy_cache_min_uses 3;

            # Explicitly declare allowed methods (GET and HEAD are always added)
            proxy_cache_methods GET HEAD;
        }
    }
}

In this configuration, responses requested through location / are written to cache zone one after 3 requests when using listed methods such as GET or HEAD. Note that backend_upstream is a placeholder representing a proxied server or upstream block defined elsewhere in the configuration.

Research Method and Limitations

This technical summary was prepared strictly from the supplied public excerpts of the Nginx ngx_http_proxy_module documentation. No competing documentation or search engine results were accessible or analyzed. The supplied documentation excerpt is truncated; for example, the introduction version for proxy_cache_min_uses is not present in the excerpt. This document includes no lab benchmarks, uptime measurements, or unverified operational claims.