Varnish is the recommended full page cache for Magento 2 in production. A well-configured Varnish serves cached category and product pages in milliseconds without touching PHP or the database. A badly configured one gives you a low hit rate, stale prices or the famous “Error 503 Backend fetch failed”.
This guide covers how to set up Varnish for Magento 2, improve the cache hit rate and fix the most common problems.
How Varnish fits into a Magento stack
A typical setup:
Visitor → Nginx (SSL termination, port 443) → Varnish (port 6081 or 80) → Nginx/PHP-FPM backend (port 8080) → Magento
Varnish does not handle HTTPS itself, so a web server or load balancer in front terminates SSL and passes plain HTTP to Varnish.
Step 1: Install a supported Varnish version
Check the Magento system requirements for your version to see which Varnish versions are supported, and install it from the official Varnish repository for your OS.
Step 2: Configure Magento to use Varnish
In the admin: Stores → Configuration → Advanced → System → Full Page Cache, set Caching Application to Varnish Cache.
Or via the command line:
bin/magento config:set system/full_page_cache/caching_application 2
Tell Magento where Varnish lives, so it can send purge requests:
bin/magento setup:config:set --http-cache-hosts=127.0.0.1:6081
Step 3: Generate the VCL
Magento generates a Varnish configuration file (VCL) for you:
bin/magento varnish:vcl:generate --export-version=6 --backend-host=127.0.0.1 --backend-port=8080 --access-list=127.0.0.1 --output-file=/etc/varnish/default.vcl
Adjust the export version to your Varnish major version, and the backend host/port to your backend web server. The access-list controls who may send purge requests.
You can also export the VCL from the admin under the Full Page Cache settings.
Step 4: Configure the backend web server
Your backend Nginx listens on port 8080 (or another internal port) and runs PHP-FPM with the standard Magento Nginx configuration. Varnish forwards requests there.
Step 5: Configure SSL termination
The front Nginx listens on 443, handles certificates and proxies to Varnish:
location / {
proxy_pass http://127.0.0.1:6081;
proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header X-Forwarded-Proto https;
proxy_set_header X-Forwarded-Port 443;
proxy_buffer_size 128k;
proxy_buffers 4 256k;
proxy_busy_buffers_size 256k;
}
The X-Forwarded-Proto header tells Magento the original request was HTTPS. Larger proxy buffers help with Magento’s large headers.
Step 6: Check that caching works
curl -sI https://www.example.com/some-category.html | grep -i -E "x-magento-cache|age|x-cache"
Request the page twice. On the second request you should see a cache hit (depending on your VCL headers, for example a growing Age header or a hit indicator). Use varnishstat and varnishlog for details:
varnishstat -1 | grep -E "cache_hit|cache_miss"
varnishlog -g request -q "ReqURL ~ '/some-category.html'"
Improving the hit rate
A low hit rate is the most common Varnish problem in Magento. Causes and fixes:
Marketing parameters split the cache
Every ?utm_source=... or ?gclid=... creates a separate cache object. Strip these parameters in vcl_recv so they do not reach the cache key (they are still available to your analytics in the browser). The generated Magento VCL already strips some; extend the list with the ones your campaigns use (for example fbclid, msclkid, gad_source).
Uncacheable blocks
A single block with cacheable="false" in layout XML makes the entire page uncacheable. Search for it:
grep -r 'cacheable="false"' app/ vendor/ --include=*.xml
Move personalised content to private content (customer sections) instead.
Cookies and headers
Custom cookies or headers that vary per user can prevent caching. Check what your extensions add.
Too-short TTL or too many purges
Large imports or extensions that purge the whole cache after every product save keep the cache cold. Purge by tags instead of full cache, and run imports at night.
Cache warming
After a deploy or full flush, the first visitors hit uncached pages. A cache warmer that crawls your most important URLs helps.
Common errors
Error 503 Backend fetch failed
Varnish could not get a valid response from the backend. Common causes:
- Backend is down or the port is wrong
- PHP fatal error (check
var/logand PHP-FPM logs) - Headers too large: Magento sends large
X-Magento-Tagsheaders on pages with many products. Increasehttp_resp_hdr_lenandhttp_resp_sizein Varnish’s startup parameters - Backend timeout: increase
first_byte_timeoutfor slow pages (and fix the slowness)
Health check failing
The generated VCL uses a health check on /pub/health_check.php (or /health_check.php depending on your document root). Make sure that URL works on the backend.
Prices or stock not updating
Purge requests are not reaching Varnish. Check --http-cache-hosts, the access list in the VCL and firewall rules.
Admin or checkout cached
The default VCL excludes admin, checkout and customer pages. If you customised the VCL, make sure those exclusions are still there.
Varnish vs built-in cache vs CDN
| Option | When to use |
|---|---|
| Built-in Magento cache | Development or very small stores |
| Varnish | Recommended for production |
| CDN with full page caching | Additional layer for global traffic; must respect Magento’s cache logic |
Frequently asked questions
Is Varnish required for Magento 2?
Not technically, but it is strongly recommended for production performance.
Does Varnish work with Hyvä?
Yes. Hyvä changes the frontend; full page caching works the same way.
What hit rate should I aim for?
It depends on traffic patterns, but on catalog pages most anonymous requests should be hits. If most requests are misses, look at parameters, uncacheable blocks and purges.
Want Varnish tuned properly?
I configure Varnish and full page caching for Magento 2 and fix hit rate and 503 issues. See also 12 reasons a Magento store is slow, my Magento 2 and Hyvä service, or request a performance check.