Vagrant 1.5 Feature Preview: Boxes 2.0

Vagrant 1.5 Feature Preview: Boxes 2.0

Feb 19 2014 Mitchell Hashimoto

Vagrant 1.5 will feature a revamped system for finding, downloading, and using boxes. With Vagrant 1.5 boxes will be easier than ever to find, build, use, update, and share. For new users, Vagrant becomes much easier to use, and for existing users, the box system becomes much more powerful with new features to help teams using Vagrant.

Here are some quick highlights of the new box system: box names are now as simple as hashicorp/precise64, which acts as both the address for the box as well as the name. A single box address can represent a box for multiple providers, so you no longer need to special-case box URLs depending on the provider in use. Boxes are now versionable, so you can deploy box updates and users of that box are notified when updates are available. And finally, we're launching a public service to share, discover, and build boxes.

And, we're also happy to say that the new system is fully backwards compatible. All old CLI commands, box files, and Vagrantfiles continue to behave exactly the way they have before.

Read on to learn more about how all these new features work as well as to learn some of the motivation behind the features.


The box system that is in place in Vagrant 1.4 and earlier has been mostly untouched since the first release of Vagrant. While the format of boxes and commands were modified slightly for Vagrant 1.1 to accommodate multiple providers, the general use has not changed at all in over four years.

During this time, we've learned a lot about how people use Vagrant and the box system:

  • Users want an easier way to find boxes, both for specific operating systems as well as complete development environments.

  • Beginners are often confused about the existing separation of the logical name of the box from its URL. For example, what is the <name> invagrant box add <name> <url> used for?

  • With the introduction of multiple providers, boxes (specifically URLs to boxes) becoming specific to a provider caused confusion and some level of frustration.

  • Box creators and organizations using Vagrant want a way to update boxes and notify Vagrant users of these updates. The idea of only using a configuration management system to keep boxes up to date doesn't always align with what the user of Vagrant really wants.

  • Box creators want a way to share the box they've made. Additionally, box hosting has always been a bit of a challenge.

We believe we've successfully addressed all of this feedback for Vagrant 1.5, building a powerful new box system while retaining complete backwards compatibility.

Box Discovery and Sharing

For years, the only way to find other boxes has been through word of mouth or community-powered listings of boxes. We've been grateful to those in the community who have helped Vagrant users discovery boxes, but we felt it was time to make discovery and sharing more official.

Coinciding with the release of Vagrant 1.5, we'll be launching a website to find and share boxes. This website supports all of the upcoming features of boxes such as shortnames, versions, multiple providers, changelogs, and more.

Users will able to sign up and share their own boxes. Boxes don't have to be physically hosted on the service. If you prefer to keep the physical box file on your own network, we're happy to simply host the metadata. Of course, we'll also allow you to upload the box files directly to us.

And for those with private boxes, you can create private boxes that are only available to people or organizations you designate. More details about all the features of this website will emerge in the coming weeks.

The availability of this resource will make it trivially easy for beginners to find a box with the technology they're looking for. Much like the existence of a library helps speed up development, the existence of pre-made environments for various technologies should speed up getting started with Vagrant.

And for existing users of Vagrant, it is now easier than ever to share and update your environments.

Interested in early access? We're looking for some people interested in early access to begin populating the site prior to launch. If you have boxes you'd like to share, please contact for more details..

Box Shortnames

Adding a box prior to Vagrant 1.5 required two pieces of information: a logical name and a URL to the box itself. The logical name would then be used as a parameter to in your Vagrantfile to map it to the proper box.

This caused some friction for new users because the reason for having a logical name in addition to the URL wasn't immediately clear. And for teams heavily using Vagrant, it was sometimes complicated to maintain a unique name across the entire team, especially since users were able to assign arbitrary names to downloaded boxes.

With Vagrant 1.5, there is now only one thing you need to know to use a box: the box name. For example, the precise64 box that we provide is now named hashicorp/precise64. Using this name is easier than ever:

$ vagrant box add hashicorp/precise64 ...

And in your Vagrantfile: = "hashicorp/precise64"

This one name can represent a box that supports multiple providers. You no longer need to maintain a list of differing URLs for each provider you want to use. Below shows what it is like to add a box that supports multiple providers:

$ vagrant box add hashicorp/precise64 This box can work with multiple providers! The providers that it can work with are listed below. Please review the list and choose the provider you will be working with. 1.) virtualbox 2.) vmware Enter your choice: _

The name is looked up in the directory of Vagrant boxes, the same website we're launching for discovery and sharing. This results in a nice, simple one-to-one mapping between the name in the directory and the name actually used with Vagrant. Also, while by default it points to our publicly hosted directory, you're able to customize this lookup location, as well.

Your browser is out-of-date!

Update your browser to view this website correctly. Update my browser now