Install and specify a box

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/bionic64 from 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 hashicorp/bionic64 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.

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

The 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 run.

You may specify an explicit version of a box by specifying config.vm.box_version for example:

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 config.vm.box_url:

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.