--- title: "How to Configure Nginx FastCGI Cache on Ubuntu 24.04" description: "Speed up PHP sites on Ubuntu 24.04 with Nginx FastCGI cache: define a cache zone, skip logged-in users, check HIT and MISS headers and purge cached pages." category: "Caching and CDN" language: en source: https://cubepath.com/docs/caching-and-cdn/nginx-fastcgi-cache-configuration updated: 2026-09-25 --- # How to Configure Nginx FastCGI Cache on Ubuntu 24.04 Every request to a PHP application normally goes through PHP-FPM, which runs the code and queries the database even when the resulting page is identical for every visitor. Nginx FastCGI cache stores those generated pages on disk and serves repeat requests directly, so PHP-FPM only works when the content actually changes. In this tutorial you will enable FastCGI caching for a PHP site on Ubuntu 24.04, exclude requests that must never be cached, verify the cache with response headers and learn how to purge it. ## Prerequisites To follow this tutorial you need: - A server running Ubuntu 24.04 LTS, for example a CubePath VPS, and a non-root user with `sudo` privileges. - Nginx and PHP-FPM installed (`sudo apt install nginx php8.3-fpm`). Ubuntu 24.04 ships PHP 8.3, whose socket is `/run/php/php8.3-fpm.sock`. - A site served from `/var/www/your_domain` with a server block in `/etc/nginx/sites-available/your_domain`. Replace `your_domain` with your own domain throughout the guide. - A few hundred MB of free disk space for the cache. ## Step 1 - Defining the cache zone The cache zone tells Nginx where to store cached responses and how much memory to use for the index of keys. It must be declared in the `http` context. On Ubuntu, every file in `/etc/nginx/conf.d/` is included inside that context, so create a dedicated file there: ```bash sudo nano /etc/nginx/conf.d/fastcgi-cache.conf ``` ```nginx fastcgi_cache_path /var/cache/nginx/fastcgi levels=1:2 keys_zone=PHPCACHE:100m inactive=60m max_size=1g; fastcgi_cache_key "$scheme$request_method$host$request_uri"; ``` What each parameter does: - `levels=1:2` spreads cached files over two levels of subdirectories so no single directory gets too large. - `keys_zone=PHPCACHE:100m` creates a shared memory zone named `PHPCACHE`. One megabyte holds about 8,000 keys, so 100 MB is enough for roughly 800,000 cached pages. - `inactive=60m` deletes entries nobody has requested for 60 minutes, even if they are still valid. - `max_size=1g` caps disk usage; when it is reached Nginx removes the least recently used entries. - `fastcgi_cache_key` defines what makes two requests "the same". Unlike proxy caching, FastCGI caching has no default key, so this line is required. Including `$scheme` and `$host` keeps HTTP and HTTPS versions, and different sites on the same server, apart. Create the cache directory and give it to the user Nginx workers run as: ```bash sudo mkdir -p /var/cache/nginx/fastcgi sudo chown -R www-data:www-data /var/cache/nginx ``` ## Step 2 - Enabling the cache in the server block Now tell the PHP location of your site to use the zone. Open the server block: ```bash sudo nano /etc/nginx/sites-available/your_domain ``` A complete server block with caching enabled looks like this: ```nginx server { listen 80; listen [::]:80; server_name your_domain www.your_domain; root /var/www/your_domain; index index.php index.html; set $skip_cache 0; location / { try_files $uri $uri/ /index.php?$args; } location ~ \.php$ { include snippets/fastcgi-php.conf; fastcgi_pass unix:/run/php/php8.3-fpm.sock; fastcgi_cache PHPCACHE; fastcgi_cache_valid 200 301 302 10m; fastcgi_cache_valid 404 1m; fastcgi_cache_bypass $skip_cache; fastcgi_no_cache $skip_cache; fastcgi_cache_use_stale error timeout updating http_500 http_503; fastcgi_cache_background_update on; fastcgi_cache_lock on; add_header X-FastCGI-Cache $upstream_cache_status always; } location ~ /\.(?!well-known) { deny all; } } ``` The caching directives work together: - `fastcgi_cache_valid` sets how long each status code stays cached when PHP does not send its own `Cache-Control` or `Expires` headers. - `fastcgi_cache_bypass` and `fastcgi_no_cache` read the `$skip_cache` variable you will fill in Step 3. The first skips reading from the cache, the second skips writing to it. - `fastcgi_cache_use_stale` with `fastcgi_cache_background_update` serves the expired copy while one request refreshes it in the background, and keeps the site up if PHP-FPM returns errors. - `fastcgi_cache_lock` makes only one request go to PHP-FPM when many visitors ask for the same uncached page at once. - The `X-FastCGI-Cache` header exposes the cache result so you can verify it. > Note: Nginx never caches a response that contains a `Set-Cookie` header or `Cache-Control: private`, `no-cache` or `no-store`. PHP sends these when the code calls `session_start()`, which is usually the right behavior. If a page is never cached, check its headers first. Test and reload: ```bash sudo nginx -t sudo systemctl reload nginx ``` ```output nginx: the configuration file /etc/nginx/nginx.conf syntax is ok nginx: configuration file /etc/nginx/nginx.conf test is successful ``` ## Step 3 - Excluding requests that must not be cached Serving a cached page to the wrong visitor is worse than not caching at all: a logged-in user could see another user's name, or a cart could show someone else's items. Add bypass rules to the server block, right after `set $skip_cache 0;`: ```nginx if ($request_method = POST) { set $skip_cache 1; } if ($query_string != "") { set $skip_cache 1; } if ($request_uri ~* "/wp-admin/|/wp-json/|/xmlrpc.php|wp-.*\.php|/feed/|sitemap(_index)?\.xml") { set $skip_cache 1; } if ($request_uri ~* "/cart/|/checkout/|/my-account/") { set $skip_cache 1; } if ($http_cookie ~* "comment_author|wordpress_[a-f0-9]+|wp-postpass|wordpress_no_cache|wordpress_logged_in|woocommerce_items_in_cart|PHPSESSID") { set $skip_cache 1; } ``` The rules skip the cache for form submissions, URLs with query strings, the WordPress admin and API, WooCommerce cart and account pages, and any visitor who has a login, comment or session cookie. They are written for WordPress and WooCommerce; for another application, keep the `POST`, query string and session cookie rules and replace the paths and cookie names with the ones your application uses for logged-in users. Using `if` with only `set` inside, at server level, is safe; the well-known problems with `if` in Nginx apply to other directives inside `location` blocks. Test and reload again: ```bash sudo nginx -t && sudo systemctl reload nginx ``` ## Step 4 - Verifying that the cache works Create a small test page that prints the current time, which makes it obvious whether a response came from PHP or from the cache: ```bash echo '