In order for your Vagrant Box to support versioning, you have to use the vagrant cloud (create an account on From Creating A Base Box:

You can distribute the box file however you’d like. However, if you want to support versioning, putting multiple providers at a single URL, pushing updates, analytics, and more, we recommend you add the box to Vagrant Cloud.

You can upload both public and private boxes to this service.

Another note is that you have to use vagrant version 1.5 or above, from Box Versioning:

Since Vagrant 1.5, boxes support versioning. This allows the people who make boxes to push updates to the box, and the people who use the box have a simple workflow for checking for updates, updating their boxes, and seeing what has changed.

So login to the vagrantcloud site and click on “Create One”:


Fill out all the information (like name and description of box):


Give the Box a version and create a comment for the version:


Assign a provider to the box:


I created this one for VirtualBox. Then provide a URL of the box file, to upload to the vagrant cloud you need to have a paid account. I uploaded my vagrant box to my test google drive account:


After that you have to release that version of the vagrant box:


After it’s successful, you will see the successful page:


At this point you can add that box to your local vagrant instance like so:

elatov@kmac:~$vagrant box add elatov/opensuse13-32
==> box: Loading metadata for box 'elatov/opensuse13-32'
    box: URL:
==> box: Adding box 'elatov/opensuse13-32' (v0.0.1) for provider: virtualbox
    box: Downloading:
==> box: Successfully added box 'elatov/opensuse13-32' (v0.0.1) for 'virtualbox'!

Now if I go back to vagrant cloud, I can add a new version. Fist click on your box in vagrant cloud:


Then click on “create a version +”:


Then name the version:


Then configure the provider for the new version:


The go ahead and release the new version:


If successful, you will see the following:


Now in your local vagrant instance you can check if any of your boxes are out of date:

elatov@kmac:~$vagrant box outdated --global
* 'opensuse13-32' wasn't added from a catalog, no version information
* 'hashicorp/precise32' (v1.0.0) is up to date
* 'elatov/opensuse13-32' is outdated! Current: 0.0.1. Latest: 0.0.2

We can see that the opensuse from the vagrant cloud is now outdated. To update the box to the latest version, you can run the following:

elatov@kmac:~$vagrant box update -b elatov/opensuse13-32
Checking for updates to 'elatov/opensuse13-32'
Latest installed version: 0.0.1
Version constraints: > 0.0.1
Provider: virtualbox
Updating 'elatov/opensuse13-32' with provider 'virtualbox' from version
'0.0.1' to '0.0.2'...
Loading metadata for box ''
Adding box 'elatov/opensuse13-32' (v0.0.2) for provider: virtualbox
Successfully added box 'elatov/opensuse13-32' (v0.0.2) for 'virtualbox'!

It doesn’t actually check the versions of the file and it will download the box again, even if it’s the same (the download takes about 5mins, 700MB from gdrive… not bad). Here is a wget of the file:

-2014-06-11 14:08:27--
Resolving (,
Connecting to (||:443... connected.
HTTP request sent, awaiting response... 302 Found
Location: [following]
--2014-06-11 14:08:28--
Resolving (,,, ...
Connecting to (||:443... connected.
HTTP request sent, awaiting response... 200 OK
Length: 721075604 (688M) [application/x-gzip]
Saving to: ‘’
100%[======================================>] 721,075,604 2.57MB/s   in 3m 15s

2014-06-11 14:11:43 (3.53 MB/s) - ‘’ saved [721075604/721075604]

FINISHED --2014-06-11 14:11:43--
Total wall clock time: 3m 17s
Downloaded: 1 files, 688M in 3m 15s (3.53 MB/s)

At this point you will have two different versions of the vmdks as well:

elatov@kmac:~$tree .vagrant.d/boxes/elatov-VAGRANTSLASH-opensuse13-32/
├── 0.0.1
│   └── virtualbox
│       ├── Vagrantfile
│       ├── box-disk1.vmdk
│       ├── box.ovf
│       └── metadata.json
├── 0.0.2
│   └── virtualbox
│       ├── Vagrantfile
│       ├── box-disk1.vmdk
│       ├── box.ovf
│       └── metadata.json
└── metadata_url

4 directories, 9 files

And vagrant will list them as separate boxes:

elatov@kmac:~$vagrant box list
elatov/opensuse13-32 (virtualbox, 0.0.1)
elatov/opensuse13-32 (virtualbox, 0.0.2)
hashicorp/precise32  (virtualbox, 1.0.0)
opensuse13-32        (virtualbox, 0)

To remove the old version you can run the following (to save space on the local machine):

elatov@kmac:~$vagrant box remove elatov/opensuse13-32 --box-version 0.0.1
Removing box 'elatov/opensuse13-32' (v0.0.1) with provider 'virtualbox'...

If for whatever reason you wanted to download the old version you could do the following:

elatov@kmac:~$vagrant box add elatov/opensuse13-32 --box-version 0.0.1
==> box: Loading metadata for box 'elatov/opensuse13-32'
    box: URL:
==> box: Adding box 'elatov/opensuse13-32' (v0.0.1) for provider: virtualbox
    box: Downloading:
==> box: Successfully added box 'elatov/opensuse13-32' (v0.0.1) for 'virtualbox'!

If you want to init an old box, you can specify the URL for the first version like so:

elatov@kmac:~/test2$vagrant init elatov/opensuse13-32
A `Vagrantfile` has been placed in this directory. You are now
ready to `vagrant up` your first virtual environment! Please read
the comments in the Vagrantfile as well as documentation on
`` for more information on using Vagrant.
elatov@kmac:~/test2$vagrant up
Bringing machine 'default' up with 'virtualbox' provider...
==> default: Importing base box 'elatov/opensuse13-32'...
==> default: Matching MAC address for NAT networking...
==> default: Checking if box 'elatov/opensuse13-32' is up to date...

You will notice the URL defined in the Vagrantfile of the old version and not in the new version:

elatov@kmac:~$grep box_url test1/Vagrantfile test2/Vagrantfile
test2/Vagrantfile:  config.vm.box_url = ""

Another note, if you don’t want to keep downloading the box file, you can repackage the downloaded box file and store it locally as well. This is accomplished with the following command:

elatov@kmac:~$vagrant box repackage elatov/opensuse13-32 virtualbox 0.0.2

then in the current directory you will have a file:

elatov@kmac:~$ls -lh pack*
-rw-r--r--  1 elatov  staff   688M Jun 11 14:30

I also ran into a cool git hub project to host your own vagrant cloud: vagrant-catalog. As long as the server/location has a valid json it should allow versioning of the box as per this google forum.

Published by Karim Elatov

21 June 2014