How to Use proxy_cache in Nginx for Efficient Caching

Use proxy_cache_path to define cache storage and proxy_cache inside a server or location block to enable caching in Nginx. This caches backend responses and serves them quickly on repeated requests.

Syntax

The proxy_cache_path directive sets the cache storage location, size, and keys. The proxy_cache directive enables caching for a specific location using the defined cache zone. Additional directives like proxy_cache_valid control cache duration.

nginx

proxy_cache_path /path/to/cache levels=1:2 keys_zone=my_cache:10m max_size=100m inactive=60m use_temp_path=off;

server {
    location / {
        proxy_pass http://backend_server;
        proxy_cache my_cache;
        proxy_cache_valid 200 302 10m;
        proxy_cache_valid 404 1m;
    }
}

Example

This example shows how to cache responses from a backend server for 10 minutes for successful requests and 1 minute for 404 errors. Cached content is stored in /var/cache/nginx with a maximum size of 100MB.

nginx

proxy_cache_path /var/cache/nginx levels=1:2 keys_zone=my_cache:10m max_size=100m inactive=60m use_temp_path=off;

server {
    listen 80;
    server_name example.com;

    location / {
        proxy_pass http://localhost:8080;
        proxy_cache my_cache;
        proxy_cache_valid 200 302 10m;
        proxy_cache_valid 404 1m;
        proxy_cache_use_stale error timeout updating;
        add_header X-Proxy-Cache $upstream_cache_status;
    }
}

Output

When accessing http://example.com/, the first request fetches from backend and caches it. Subsequent requests within 10 minutes serve cached content with header 'X-Proxy-Cache: HIT'.

Common Pitfalls

• Not defining proxy_cache_path before using proxy_cache causes errors.
• Cache keys default to request URI; dynamic query strings may cause cache misses.
• Forgetting to set proxy_cache_valid leads to default caching times that may not suit your needs.
• Not handling stale cache with proxy_cache_use_stale can cause downtime if backend is slow or unavailable.

nginx

## Wrong: Missing proxy_cache_path
server {
    location / {
        proxy_pass http://backend;
        proxy_cache my_cache;  # Error: my_cache not defined
    }
}

## Right: Define proxy_cache_path
proxy_cache_path /var/cache/nginx levels=1:2 keys_zone=my_cache:10m max_size=100m;

server {
    location / {
        proxy_pass http://backend;
        proxy_cache my_cache;
    }
}

Quick Reference

Directive	Purpose	Example
proxy_cache_path	Defines cache storage and zone	proxy_cache_path /cache levels=1:2 keys_zone=zone:10m max_size=50m;
proxy_cache	Enables caching in location	proxy_cache zone;
proxy_cache_valid	Sets cache duration per status	proxy_cache_valid 200 10m;
proxy_cache_use_stale	Serve stale cache on errors	proxy_cache_use_stale error timeout;
add_header	Add cache status header	add_header X-Cache-Status $upstream_cache_status;

Key Takeaways

Always define proxy_cache_path before enabling proxy_cache in a location.

Use proxy_cache_valid to control how long responses stay cached.

Add proxy_cache_use_stale to improve reliability during backend issues.

Check cache status with headers like X-Proxy-Cache for debugging.

Cache keys depend on request URI; adjust if query strings vary.