Instead of building a virtual machine from scratch, which would be a slow and tedious process, Vagrant uses a base image to quickly clone a virtual machine. These base images are known as "boxes" in Vagrant, and specifying the box to use for your Vagrant environment is always the first step after creating a new Vagrantfile.
»Install a Box (Optional)
If you ran the commands in the last tutorial you do not need to add a box; Vagrant installed one when you initialized your project. Sometimes you may want to install a box without creating a new Vagrantfile. For this you would use the
box add subcommand.
You can add a box to Vagrant with
vagrant box add. This stores the box
under a specific name so that multiple Vagrant environments can re-use it.
If you have not added a box yet, do so now. Vagrant will prompt you to select a provider. Type
2 and press
Enter to select Virtualbox.
$ vagrant box add hashicorp/bionic64
This will download the box named
HashiCorp's Vagrant Cloud box catalog, where you can find
and host boxes.
Boxes are globally stored for the current user. Each project uses a box
as an initial image to clone from, and never modifies the actual base
image. This means that if you have two projects both using the
box you just added, adding files in one guest machine will have no effect
on the other machine.
In the above command, you will notice that boxes are namespaced. Boxes are
broken down into two parts—the username and the box name—separated by a
slash. In the example above, the username is
hashicorp, and the box is
bionic64. You can also specify boxes via URLs or local file paths, but that
will not be covered in the getting started guide.
Warning: Namespaces do not guarantee canonical boxes, and anyone can publish boxes on Vagrant Cloud. HashiCorp's support team does not assist with third-party published boxes.
»Use a Box
Now you've added a box to Vagrant either by initializing or adding it explicitly, you need to configure your
project to use it as a base. Open the
Vagrantfile and replace the
contents with the following.
Vagrant.configure("2") do |config| config.vm.box = "hashicorp/bionic64" end
hashicorp/bionic64 in this case must match the name you used to add
the box above. This is how Vagrant knows what box to use. If the box was not
added before, Vagrant will automatically download and add the box when it is
You may specify an explicit version of a box by specifying
Vagrant.configure("2") do |config| config.vm.box = "hashicorp/bionic64" config.vm.box_version = "1.0.282" end
You may also specify the URL to a box directly using
Vagrant.configure("2") do |config| config.vm.box = "hashicorp/bionic64" config.vm.box_url = "https://vagrantcloud.com/hashicorp/bionic64" end
In the next tutorial, we will bring up the Vagrant environment and interact with it.
»Find More Boxes
For the remainder of these tutorials, you will only use the
hashicorp/bionic64 box you added. Once you're ready to start using Vagrant in your development workflow you will need to know how to discover other boxes.
The best place to find more boxes is HashiCorp's Vagrant Cloud box catalog. HashiCorp's Vagrant Cloud has a public directory of freely available boxes that run various platforms and technologies. You can search Vagrant Cloud to find the box you care about.
You can also host your own boxes on Vagrant Cloud. Paid accounts can host private boxes to share privately within an organization.
You have successfully downloaded your first Vagrant box and configured the Vagrantfile to use that box. Continue to the next tutorial to bringing up the machine and access it via SSH.