» Box Versioning

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

If you are just getting started with Vagrant, box versioning is not tooimportant, and we recommend learning about some other topics first. Butif you are using Vagrant on a team or plan on creating your own boxes,versioning is very important. Luckily, having versioning built right into Vagrant makes it easy to use and fit nicely into the Vagrant workflow.

This page will cover how to use versioned boxes. It does not cover howto update your own custom boxes with versions. That is covered increating a base box.

» Viewing Versions and Updating

vagrant box list only shows installed versions of boxes. If you wantto see all available versions of a box, you will have to find the boxon HashiCorp's Vagrant Cloud. An easy way to find a boxis to use the url https://vagrantcloud.com/$USER/$BOX. For example, forthe hashicorp/precise64 box, you can find information about it athttps://vagrantcloud.com/hashicorp/precise64.

You can check if the box you are using is outdated with vagrant box outdated.This can check if the box in your current Vagrant environment is outdatedas well as any other box installed on the system.

Finally, you can update boxes with vagrant box update. This will downloadand install the new box. This will not magically update running Vagrantenvironments. If a Vagrant environment is already running, you will have todestroy and recreate it to acquire the new updates in the box. The updatecommand just downloads these updates locally.

» Version Constraints

You can constrain a Vagrant environment to a specific version or versionsof a box using the Vagrantfile by specifyingthe config.vm.box_version option.

If this option is not specified, the latest version is always used. This isequivalent to specifying a constraint of ">= 0".

The box version configuration can be a specific version or a constraint ofversions. Constraints can be any combination of the following:= X, > X, < X, >= X, <= X, ~> X. You can combine multipleconstraints by separating them with commas. All the constraints should beself explanatory except perhaps for ~>, known as the "pessimistic constraint".Examples explain it best: ~> 1.0 is equivalent to >= 1.0, < 2.0. And~> 1.1.5 is equivalent to >= 1.1.5, < 1.2.0.

You can choose to handle versions however you see fit. However, many boxesin the public catalog follow semantic versioning.Basically, only the first number (the "major version") breaks backwardscompatibility. In terms of Vagrant boxes, this means that any software thatruns in version "1.1.5" of a box should work in "1.2" and "1.4.5" and so on,but "2.0" might introduce big changes that break your software. By followingthis convention, the best constraint is ~> 1.0 because you know it is safeno matter what version is in that range.

Please note that, while the semantic versioning specification allows formore than three points and pre-release or beta versions, Vagrant boxes must beof the format X.Y.Z where X, Y, and Z are all positive integers.

» Automatic Update Checking

Using the Vagrantfile, you can also configureVagrant to automatically check for updates during any vagrant up. This isenabled by default, but can easily be disabled withconfig.vm.box_check_update = false in your Vagrantfile.

When this is enabled, Vagrant will check for updates on every vagrant up,not just when the machine is being created from scratch, but also when itis resuming, starting after being halted, etc.

If an update is found, Vagrant will output a warning to the user lettingthem know an update is available. That user can choose to ignore the warningfor now, or can update the box by running vagrant box update.

Vagrant can not and does not automatically download the updated box andupdate the machine because boxes can be relatively large and updating themachine requires destroying it and recreating it, which can cause importantdata to be lost. Therefore, this process is manual to the extent that theuser has to manually enter a command to do it.

» Pruning Old Versions

Vagrant does not automatically prune old versions because it does not knowif they might be in use by other Vagrant environments. Because boxes canbe large, you may want to actively prune them once in a while usingvagrant box remove. You can see all the boxes that are installedusing vagrant box list.

Another option is to use vagrant box prune command to remove all installed boxes that are outdated and not currently in use.