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.
If you are just getting started with Vagrant, box versioning is not too important, and we recommend learning about some other topics first. But if you are using Vagrant on a team or plan on creating your own boxes, versioning is very important. Luckily, having versioning built right in to 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 how to update your own custom boxes with versions. That is covered in creating a base box.
Viewing Versions and Updating
vagrant box list only shows installed versions of boxes. If you want
to see all available versions of a box, you will have to find the box
on HashiCorp's Vagrant Cloud. An easy way to find a box
is to use the url https://vagrantcloud.com/$USER/$BOX. For example, for
the hashicorp/bionic64 box, you can find information about it at
https://vagrantcloud.com/hashicorp/bionic64.
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 outdated
as well as any other box installed on the system.
Finally, you can update boxes with vagrant box update. This will download
and install the new box. This will not magically update running Vagrant
environments. If a Vagrant environment is already running, you will have to
destroy and recreate it to acquire the new updates in the box. The update
command just downloads these updates locally.
Version Constraints
You can constrain a Vagrant environment to a specific version or versions
of a box using the Vagrantfile by specifying
the config.vm.box_version option.
If this option is not specified, the latest version is always used. This is equivalent to specifying a constraint of ">= 0".
The box version configuration can be a specific version or a constraint of
versions. Constraints can be any combination of the following:
= X, > X, < X, >= X, <= X, ~> X. You can combine multiple
constraints by separating them with commas. All the constraints should be
self 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 boxes
in the public catalog follow semantic versioning.
Basically, only the first number (the "major version") breaks backwards
compatibility. In terms of Vagrant boxes, this means that any software that
runs 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 following
this convention, the best constraint is ~> 1.0 because you know it is safe
no matter what version is in that range.
Please note that, while the semantic versioning specification allows for
more than three points and pre-release or beta versions, Vagrant boxes must be
of the format X.Y.Z where X, Y, and Z are all positive integers.
Automatic Update Checking
Using the Vagrantfile, you can also configure
Vagrant to automatically check for updates during any vagrant up. This is
enabled by default, but can easily be disabled with
config.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 it
is resuming, starting after being halted, etc.
If an update is found, Vagrant will output a warning to the user letting
them know an update is available. That user can choose to ignore the warning
for now, or can update the box by running vagrant box update.
Vagrant can not and does not automatically download the updated box and update the machine because boxes can be relatively large and updating the machine requires destroying it and recreating it, which can cause important data to be lost. Therefore, this process is manual to the extent that the user has to manually enter a command to do it.
Pruning Old Versions
Vagrant does not automatically prune old versions because it does not know
if they might be in use by other Vagrant environments. Because boxes can
be large, you may want to actively prune them once in a while using
vagrant box remove. You can see all the boxes that are installed
using 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.