A “box” is the base image used to create a virtual environment with Vagrant. It is meant to be a portable file which can be used by others on any platform that Vagrant runs in order to bring up a running virtual environment. The
vagrant box utility provides all the power for managing boxes, and
vagrant package is used to create boxes.
Boxes provide only the base image for Vagrant. The moment you run
vagrant up, the box is copied so that it can be modified for that virtual machine. Therefore, it is safe to remove or update the box after a virtual machine has been created.
Boxes can be installed from the filesystem or via HTTP (note that if you’re interested, it’s quite easy to extend this to support more protocols). No matter the source, the installation method is the same. The following adds a box named
lucid32 to a local vagrant installation:
$ vagrant box add lucid32 http://files.vagrantup.com/lucid32.box
The name used with the
vagrant box add command is the name used to reference the box from that point forward. Any box can be named anything you want. Boxes that are added using
vagrant box add are global to the vagrant install, and they are stored at
~/.vagrant.d/boxes on the local filesystem.
Note: The default Vagrantfile created with
vagrant init defaults to using a box named “base.” This is why in the getting started guide, the first few commands tell you to add a box named “base” to the project. However, the name of the box is not significant in any way other than to logically identify the box in a Vagrantfile or from the command line.
Boxes can just as easily be removed using the same
vagrant box command. The following command removes the
lucid32 box which was added in the previous section:
$ vagrant box remove lucid32
Warning: There is no going back from this command. This command literally deletes the files off the filesystem.
Keeping track of the installed boxes can be difficult. Vagrant provides the
vagrant box list command to list all installed boxes.
$ vagrant box list lucid32
Boxes are created from a vagrant project. So the first step to creating a box is to setup a project the way you want. Add provisioning, share folders, etc. Anything you need to get your environment in the correct state. Once there, just run
vagrant package and it’ll package the environment and save it to
package.box in the current working directory.
vagrant package will not include the Vagrantfile or any files other than the exported virtual machine. If you wish to include additional files or a Vagrantfile, use the
--vagrantfile options, respectively. An example below:
$ vagrant package --vagrantfile Vagrantfile.pkg --include README.txt