Skip to content
Tutorials Center
My learning

Topics

Lesson 28 of 36 ยท Team Workflows

Version Constraints and Pinned Boxes

Make environments reproducible by pinning Vagrant, box and plugin versions with Vagrant.require_version, config.vm.box_version and update policies for teams.

"It works on my machine" has a Vagrant-specific cousin: "it works with my version of the box". Boxes get updated, Vagrant releases change behavior, and a plugin upgrade can break a Vagrantfile overnight. The cure is to state which versions your environment was tested with and make Vagrant check them. This lesson shows the three places to pin versions and how to upgrade deliberately.

Requiring a Vagrant version

Vagrant.require_version stops the run with a clear message when the installed Vagrant is outside the range.

Ruby
Vagrant.require_version ">= 2.3.0", "< 3.0"

Vagrant.configure("2") do |config|
  config.vm.box = "ubuntu/jammy64"
end
TEXT
$ vagrant up
Vagrant failed to initialize at a very early stage:

The version of Vagrant you're running is not compatible with this Vagrantfile.
Required: >= 2.3.0, < 3.0

Put it on the first line of the Vagrantfile. The constraint syntax is the same as RubyGems: >=, <, ~> (pessimistic) and =.

The pessimistic operator is the one you will use most. "~> 2.4" means "at least 2.4, but below 3.0". "~> 2.4.1" means "at least 2.4.1, but below 2.5".

Pinning the box version

Without a version, vagrant up downloads the latest release of a box the first time. Two teammates starting a week apart can get different base images, which means different kernels and packages.

Ruby
config.vm.box = "ubuntu/jammy64"
config.vm.box_version = "20240115.0.0"

You can also use a constraint, for example "~> 20240115.0", to accept patch-level updates. When Vagrant starts a machine, it checks the pinned version and downloads it if missing.

Related settings:

Setting Effect
config.vm.box_version = "1.2.3" Use exactly this version (or a constraint)
config.vm.box_check_update = false Do not look for newer versions on each vagrant up
config.vm.box_url Where to download the box when it is not on Vagrant Cloud
config.vm.box_download_checksum Verify the download with a hash (with box_download_checksum_type)

Look at what is installed with vagrant box list and what is outdated with vagrant box outdated:

TEXT
$ vagrant box outdated
* 'ubuntu/jammy64' for 'virtualbox' is outdated! Current: 20240115.0.0. Latest: 20240601.0.0

Updating deliberately

Treat a box update like a dependency update: do it in a branch and test it.

  1. Run vagrant box outdated to see what is available.
  2. Change box_version in a branch.
  3. Rebuild from scratch: vagrant destroy -f && vagrant up.
  4. Run your tests inside the machine.
  5. Merge, and tell the team to run vagrant destroy -f && vagrant up once.

Old versions pile up and use gigabytes. Clean them occasionally:

TEXT
$ vagrant box prune          # remove old versions not in use
$ vagrant box remove ubuntu/jammy64 --box-version 20231201.0.0

Pruning keeps the versions that active machines use, so it is safe to run after upgrades.

Pinning plugin versions

Plugins are updated by vagrant plugin update. To lock them, state the version when installing, or declare it in the Vagrantfile.

Ruby
Vagrant.configure("2") do |config|
  config.vagrant.plugins = {
    "vagrant-hostmanager" => { "version" => "1.8.10" },
    "vagrant-vbguest"     => { "version" => "0.32.0" }
  }
end

A mismatched plugin is one of the most common reasons a once-working project fails after a laptop refresh. See Vagrant plugins for the install commands.

Reproducible provisioning too

A box version pins the operating system image, but provisioning scripts can still drift. apt-get install nginx installs whichever version the repository offers today. Reduce drift by:

  • naming package versions where it matters (apt-get install nginx=1.18.0-6ubuntu14);
  • using lockfiles for language dependencies (composer.lock, package-lock.json, Gemfile.lock);
  • building a custom box that already contains the slow-changing parts (see packaging and private boxes).

A stand-in: checking version ranges

Vagrant's constraints come from Ruby's Gem::Requirement class, which you can try in plain Ruby right here. This is the real class Vagrant uses for its range checks, applied to made-up versions.

Ruby Evaluate version constraints

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with gets), it gets the next line from this box.

Notice that ~> 20240115.0 accepts 20240115.3.0 but rejects 20240601.0.0: the first segment must match exactly, and only the last part may grow.

A team policy that works

  • State a supported range for Vagrant and the provider in the README and enforce it with Vagrant.require_version.
  • Pin box_version and bump it in dedicated pull requests.
  • Declare plugins in the Vagrantfile, with versions for fragile ones.
  • Set box_check_update = false for daily use so vagrant up does not wait on the network, and run vagrant box outdated on a schedule instead.

Common mistakes

  • No box version at all, which makes the base image a moving target.
  • A constraint too tight to ever upgrade (= 2.4.1), forcing a rewrite for harmless patches.
  • Updating the box but not rebuilding. A running machine keeps its old image until you destroy and recreate it.
  • Letting old box versions fill the disk. Run vagrant box prune after upgrades.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. What does Vagrant.require_version "~> 2.4" accept?

    The pessimistic operator allows increases in the last specified segment only, so ~> 2.4 means >= 2.4 and < 3.0.
  2. 2. Why pin config.vm.box_version?

    Without a pin, new machines get whatever the latest box version is at the time.
  3. 3. You bump box_version in the Vagrantfile. Your running machine...

    A machine is created from the box once; changing the version affects only new machines.
  4. 4. Which command removes old, unused box versions?

    prune removes older versions that no active machine uses.

Summary

  • Vagrant.require_version guards the Vagrant version; ~> is the most useful operator.
  • Pin config.vm.box_version, update it deliberately in a branch, and rebuild to apply it.
  • Declare plugin versions in the Vagrantfile and prune old boxes to save disk.
  • Reduce drift further with lockfiles and custom boxes.

Next: Triggers and automation