NginxHow-ToBeginner · 4 min read

How to Use proxy_cache_path in Nginx for Efficient Caching

Use proxy_cache_path in the http block of your Nginx configuration to define the cache storage location, size, and keys. Then enable caching in your server or location block with proxy_cache pointing to that cache zone.

📐

Syntax

The proxy_cache_path directive defines where and how Nginx stores cached files. It is placed inside the http block and includes parameters like path (directory for cache files), keys_zone (shared memory zone name and size), and optional settings like max_size (maximum cache size), inactive (time before cached items expire), and levels (directory structure depth).

nginx

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

💻

Example

This example shows how to set up proxy_cache_path in the http block and enable caching in a location block that proxies requests to an upstream server. It caches responses for faster delivery and reduces load on the backend.

nginx

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

    server {
        listen 80;

        location / {
            proxy_pass http://backend_server;
            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-Cache-Status $upstream_cache_status;
        }
    }
}

⚠️

Common Pitfalls

Placing proxy_cache_path outside the http block: It must be inside http, not server or location.
Not defining keys_zone properly: The shared memory zone name and size are required for caching to work.
Using use_temp_path=on (default) with slow disks: It can cause performance issues; setting use_temp_path=off is often better.
Forgetting to set proxy_cache in the location block: Defining the cache path alone does not enable caching.
Cache directory permissions: Ensure Nginx has write permissions to the cache directory.

nginx

## Wrong: proxy_cache_path outside http block
# events {
#     proxy_cache_path /var/cache/nginx keys_zone=my_cache:10m;
# }

## Right: proxy_cache_path inside http block
http {
    proxy_cache_path /var/cache/nginx keys_zone=my_cache:10m;
}

📊

Quick Reference

Remember these key points when using proxy_cache_path:

path: Directory to store cached files.
keys_zone=name:size: Defines cache zone name and memory size.
max_size: Limits total cache size on disk.
inactive: Time after which unused cache items expire.
levels: Controls subdirectory structure for cache files.
Always enable caching with proxy_cache in location or server blocks.

✅

Key Takeaways

Define proxy_cache_path inside the http block to set cache storage and parameters.

Use proxy_cache in location or server blocks to activate caching with the defined cache zone.

Set keys_zone with a name and memory size to enable shared cache metadata storage.

Ensure Nginx has write permissions to the cache directory to avoid errors.

Use proxy_cache_valid to control how long responses stay cached for different status codes.