Skip to content
Tutorials Center
My learning

Topics

Lesson 6 of 36 ยท Vagrantfile and Boxes

Choosing a Box

What a Vagrant box is, how to find trustworthy boxes on Vagrant Cloud, how to pin versions and check updates, and how to pick the right OS image.

A box is the starting point of every Vagrant machine: a packaged disk image plus a little metadata, the way a Docker image is the starting point of a container. When you write config.vm.box = "bento/ubuntu-24.04", you are asking Vagrant for a box called ubuntu-24.04 published by the user (or organization) bento. Choosing the right box saves hours: a good one boots reliably, is updated regularly, and matches the system you deploy to.

Where boxes come from

Boxes are published on Vagrant Cloud (the catalog at app.vagrantup.com), which is the default place Vagrant looks. A box name has the form organization/name. A box is also tied to a provider: the same Ubuntu image exists as a VirtualBox box, a VMware box, a Hyper-V box and so on, and a box page lists which providers are available. Vagrant picks the one that matches the provider you use.

Boxes can also come from other places:

  • A local file: config.vm.box = "ubuntu" plus config.vm.box_url = "file:///D:/boxes/ubuntu.box".
  • A URL to a .box file or a JSON metadata file on your own server.
  • A private registry or an artifact server inside a company.
Ruby
Vagrant.configure("2") do |config|
  config.vm.box = "internal/ubuntu-hardened"
  config.vm.box_url = "https://artifacts.example.com/boxes/ubuntu-hardened.json"
end

Well-known box families

Box What it is Notes
bento/* (e.g. bento/ubuntu-24.04, bento/debian-12, bento/rockylinux-9) Slim, well-maintained images built from open Packer templates Good default for several distributions and providers
ubuntu/* (e.g. ubuntu/jammy64) Images from the Ubuntu publisher Large disk, includes extra tools
generic/* (e.g. generic/ubuntu2204, generic/alpine319) Many distributions with VirtualBox, VMware, Hyper-V and libvirt builds Handy for libvirt and Hyper-V
gusztavvargadr/* Windows Server and Windows 11 evaluation images For Windows guests
hashicorp-education/* Small boxes made for learning Used in official tutorials

Names and availability change over time. Before you commit to one, open its page on Vagrant Cloud and check:

  1. Which providers it supports (VirtualBox? libvirt? ARM64?).
  2. The date of the last release. An image that was last built three years ago has an old kernel and old packages.
  3. How many downloads it has, and who publishes it. Prefer official publishers or boxes built from public build scripts.
  4. The OS version matches production (Ubuntu 24.04 in the box if your servers run 24.04).

A box is software you run with full access to your files through the synced folder. Only use boxes from sources you trust, and never ignore warnings about checksum or certificate failures. In a company, host an approved set of boxes in your own registry.

Using a box in the Vagrantfile

Ruby
Vagrant.configure("2") do |config|
  config.vm.box = "bento/ubuntu-24.04"
  config.vm.box_version = "~> 202508.0"   # accept patch releases of one build series
  config.vm.box_check_update = true       # tell me when a newer version exists
end

config.vm.box_version accepts a version constraint. Without it Vagrant uses the latest version when it first downloads, and an existing cached version afterward, so two teammates may end up on different builds. For team work, pin it. Common forms:

Constraint Meaning
"202508.03.0" Exactly this version
">= 202501.0" This version or newer
"~> 202508.0" At least 202508.0 and below 202509 (pessimistic constraint)
">= 1.0, < 2.0" A range

You can try these rules with plain Ruby, which uses the same constraint syntax as RubyGems:

Ruby Version constraints for box_version (Ruby)

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.

(Real box versions may use plain numbers like 1.2.3 or dates; the constraint logic is identical.)

Matching the box to your project

Think about the project, not about the distribution you like:

  • Developing a web app that runs on Ubuntu in production? Use an Ubuntu box of the same major version.
  • Testing an Ansible role for several distributions? Use one box per distribution, with a multi-machine Vagrantfile.
  • Building a Windows application? Use a Windows box; expect 40 GB downloads and long boots.
  • Little RAM? Prefer minimal images (Alpine, Debian) over desktop ones.
  • Apple Silicon or ARM server? Use an arm64 capable box and provider.
  • Need libvirt on Linux? Look for the libvirt provider on the box page.

Box naming and shortcuts

A short name without a slash, such as config.vm.box = "ubuntu", only works if you added a box with that local name yourself (see Managing boxes). That is a handy trick: the name is only a label inside your machine. The two-part user/name form always refers to Vagrant Cloud.

When a box is downloaded, Vagrant verifies it if a checksum is configured:

Ruby
config.vm.box_download_checksum = "9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08"
config.vm.box_download_checksum_type = "sha256"

This matters mostly for boxes loaded from a box_url that does not provide signed metadata.

Common mistakes

  • Not pinning versions: a surprise upgrade changes the guest between two vagrant destroy/up cycles.
  • Choosing a box with a missing provider: the error is "The box you're attempting to add doesn't support the provider you requested". Check the provider list on the box page.
  • Mixing box names with typos: bento/ubuntu24.04 versus bento/ubuntu-24.04 fails with a 404; copy the name from the catalog.
  • Assuming the vagrant user is the same: most public boxes use vagrant with the well-known insecure key; check the box description.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. What does the box name bento/ubuntu-24.04 mean?

    Box names are organization/name on Vagrant Cloud.
  2. 2. Why should team projects pin config.vm.box_version?

    Without a pin, different teammates can end up with different build versions.
  3. 3. What does the constraint ~> 202508.0 allow?

    The pessimistic operator allows increases in the last specified segment only: 202508.x.
  4. 4. You see 'box doesn't support the provider you requested'. What is the cause?

    A box is built per provider; check the providers listed on its catalog page.

Summary

  • A box is the base image; names look like organization/name and come from Vagrant Cloud or your own server.
  • Check provider support, release date, publisher and OS version before choosing.
  • Pin config.vm.box_version in team projects, using exact versions or ~> ranges.
  • Only use boxes you trust; consider an internal registry for company work.

Next: Managing Boxes