Tools for Varnish, including mass purging and cache warming
You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
Rob Miller 350dfa65fe Fix bug when purging a URL without a path 8 years ago
bin Unit tests for DomainPurger 8 years ago
lib Fix bug when purging a URL without a path 8 years ago
test Add tests for comment parsing in Spider 8 years ago
.gitignore Fix Gemspec for new installs 8 years ago
.travis.yml Add Travis CI config file 8 years ago
.yardopts First round of inline documentation of our functionality 8 years ago
Gemfile Bundler and gemspec 8 years ago
LICENSE Add MIT license 8 years ago Make sure Travis status badge only reflects master 8 years ago
Rakefile Unit tests for Purger 8 years ago
varnisher.gemspec Unit tests for Purger 8 years ago


Build Status

Administering Varnish is generally a breeze, but sometimes you want to do one of the few things that aren’t painless out of the box. Hopefully, that’s where this toolbox comes in.

Varnisher lets you do things like:

  • Purge a webpage and everything (e.g. images, JavaScript files, CSS files) referenced on that page
  • Spider an entire domain — useful for priming a cache
  • Purge an entire domain, including optionally re-spidering it afterwards to keep the cache warm

Full documentation is available on


Varnish requires Ruby >1.9.3 to run. If you’ve got a recent Ruby installed, then Varnisher can be installed easily via RubyGems.

Varnisher is still in beta; you can install it with:

gem install varnisher --pre



varnisher (purge|spider) [options]+

Varnisher is a set of tools for working with the Varnish HTTP cache.

--verbose, -v
    If given, Varnisher will be noisier about what it's up to.
--hostname=hostname, -H (0 ~> hostname=localhost)
    The hostname/IP address of your Varnish server.
--port=port, -p (0 ~> int(port=80))
    The port Varnish is listening on.
--help, -h

varnisher purge
varnisher spider
varnisher purge --reindex

If you find yourself typing certain parameters every time you use the script, you can specify them in an RC file called .varnishrc in your home directory. The file format is YAML and the default options are, if you want to paste and override them:

verbose: false
hostname: localhost
port: 80
num-pages: -1
ignore-hashes: true
ignore-query-strings: false


Purging a page and all the resources on it

Quite often, it’s necessary redevelop a page on a website in a way that involves changes not only to the page but also to CSS files, images, JavaScript files, etc. Purging pages in this instance can be a painful process, or at least one that requires a few ban commands in varnishadm. No longer!

Just enter:

$ varnisher purge

…and /path/to/page, along with all its images, CSS files, JavaScript files, and other external accoutrements, will be purged from Varnish’s cache.

As a bonus, this action is multithreaded, meaning even resource-heavy pages should purge quickly and evenly.

This action requires your VCL to have something like the following, which is fairly standard:

if (req.request == "PURGE") {
    if ( client.ip ~ auth ) {
        ban("obj.http.x-url == " + req.url + " && obj.http.x-host == " +;
        error 200 "Purged.";

(For an explanation of just what obj.http.x-url means, and why you should use it rather than req.url, see this page.)

Purging an entire domain

Provided your VCL has something akin to the following in it:

if ( req.request == "DOMAINPURGE" ) {
        if ( client.ip ~ auth ) {
                ban("obj.http.x-host == " +;
                error 200 "Purged.";

…then you should be able to quickly purge an entire domain’s worth of pages and resources by simply issuing the command:

$ varnisher purge

Repopulating the cache

If you’ve purged a whole domain, and particularly if your backend is slow, you might want to quickly repopulate the cache so that users never see your slow misses. Well, you can! Use the spider action:

$ varnisher spider

spider accepts either a hostname or a URL as its starting point, and will only fetch pages on the same domain as its origin. You can limit the number of pages it will process using the -n parameter:

$ varnisher -n 500 spider

If you’d like to combine purging and spidering, you can use the reindex option:

$ varnisher purge --reindex

…which is functionally equivalent to:

$ varnisher purge
$ varnisher spider