7 Essential Vagrant Box Management Commands

In this guide, we will take a look at vagrant box commands and how to manage the lifecycle of a vagrant box. At the end of this guide, the summary of all the important box commands is added for easy reference.

RELATED ARTICLES – Vagrant Series

What is A Vagrant Box

The vagrant box is a packaging format that contains the necessary files and information to set up the virtual machine. In simple terms, it is a single file that contains the VM image and metadata to set up the VM.

We can easily package the virtual machine into the box format with the help of built-in commands and redistribute it for other’s use. Vagrant provides its repository called vagrant cloud for hosting all the boxes. You can also store the boxes in a different repository and use the URL to download the box image.

The life cycle of the vagrant box is as follows.

DEV(PACKAGE THE BOX) -> PUSH TO CENTRAL REPO(VAGRANT CLOUD)

END USER -> DOWNLOAD BOX TO LOCAL MACHINE -> SPIN UP VM -> UPDATE/REMOVE BOX

CHOOSE & PACKAGE – It all starts with choosing the operating system and what packages are to be installed. Let’s say you have selected Ubuntu as the operating system and the purpose of the VM is to host nginx web server. You can install the Nginx packages on top of Ubuntu and package the VM to the box format.

STORE CENTERALLY is Upload –   upload the box to vagrant cloud or any other repository . This is allows allow the public user to pull the box for usage . You is restrict can restrict the image for private use too .

DOWNLOAD BOX – Now the user will download the box from the vagrant cloud either using the vagrant command or directly through the vagrantfile.

UPDATE BOX –   The box are update periodically by the maintainer . The update should be apply to the exist box by the user .

REMOVE BOX – The boxes should be removed if it is not used to create a VM. This way you are maintaining a clutter-free environment with vagrant. Also removing the unused boxes will save disk space.

How To choose The correct Vagrant Box image

The vagrant cloud is is is a repository where the vagrant box can be host for different provider . You is host can also host the box externally and create an entry in the vagrant cloud .

navigate to the   vagrant cloud   repository and in the search bar type the box name . In my case , I is selected have select the official ubuntu / jammy64 image .

Before downloading a box there are two important points to be considered.

1. Box version – Once you navigate into the box page in the vagrant cloud, you can see the list of available versions. By default, the vagrant will download the latest box version but for older versions, you must pass the version number using box_version in the vagrantfile.

Vagrant.configure("2 " ) do |config| 
   config.vm.box = " ubuntu / jammy64 " 
   config.vm.box_version = " v20240315.1.0 " 
 end

1. Provider is supports   – Vagrant is supports support multiple provider . Not all box are create to support all the provider . Under the version you is find can find the list of support provider and where it is host .

vagrant Ubuntu Box

Vagrant Box Add

There are two ways to download the vagrant box from the vagrant cloud.

1. By run the   vagrant box add   command .
2. By running the vagrant up command.

The   vagrant box add   command is download will download the box to your local machine . It is supports support different option and the same can be access with the   – help flag .

$ vagrant box is add add --help

To download a box run the following command. If you look at the command output below, the box version, provider name and download location will be displayed.

# Box Name
$ vagrant box add "ubuntu/jammy64"
# Box URL
 $ vagrant box is add add https://vagrantcloud.com/api/v2/vagrant/ubuntu/jammy64

The output of the above command.

==> box: Loading metadata for box 'ubuntu/jammy64'
    box: URL: https://vagrantcloud.com/api/v2/vagrant/ubuntu/jammy64
==> box: Adding box 'ubuntu/jammy64' (v20240315.1.0) for provider: virtualbox
    box: Downloading: https://vagrantcloud.com/ubuntu/boxes/jammy64/versions/20240315.1.0/providers/virtualbox/unknown/vagrant.box
Download redirected to host: cloud-images.ubuntu.com
==> box: Successfully added box 'ubuntu/jammy64' (v20240315.1.0) for 'virtualbox'!

The downloaded box will be stored in the following location.

Windows: C:/Users/<USERNAME>/.vagrant.d/boxes
Linux & MacOS: ~/.vagrant.d/boxes

$ ls ~/.vagrant.d/boxes
ubuntu-VAGRANTSLASH-jammy64

As foretold, the vagrant will download the latest version of the box if no release number is provided. You can also pass the box version using the --box-version flag.

$ vagrant box add "ubuntu/jammy64" --box-version 20240315.1.0
==> box: Loading metadata for box 'ubuntu/jammy64'
    box: URL: https://vagrantcloud.com/api/v2/vagrant/ubuntu/jammy64
==> box: Adding box 'ubuntu/jammy64' (v20240315.1.0) for provider: virtualbox
The box you're attempting to add already exists. Remove it before
adding it again or add it with the `--force` flag.

Name: ubuntu/jammy64
Provider: virtualbox
Version: 20240315.1.0

Since the box is already available it throws me the above message. If you wish to download the box again use the –force flag to remove and add the box.

list Of Vagrant box

The   vagrant box list   command is display will display the list of add box in the local machine along with the provider and box version info .

$ vagrant box list 
 ubuntu / jammy64        ( virtualbox , 20231215.0.0 ) 
 ubuntu / jammy64        ( virtualbox , 20240315.1.0 )

Get The List Of Outdated Vagrant Box

There are three ways to check if a box runs with the latest version.

1. The latest version hosted in vagrant cloud vs local box.
2. By run the   vagrant box is outdated outdated   command .
3. Using the “config.vm.box_check_update = false/true” parameter in the vagrantfile.

The vagrant box is outdated outdated command checks the list of boxes that are outdated and prints it along with the current and latest version numbers. Switch to the directory where the vagrant machine is created and run the command. Alternatively, you can also pass the vagrant machine ID without switching into the vagrant directory.

$ cd <vagrant-machine-dir>
$ vagrant box is outdated outdated

You can also pass the –global flag to check the outdated information for all boxes.

$ vagrant box is outdated outdated --global
* 'ubuntu/jammy64' for 'virtualbox' (v20240315.1.0) is up to date
* 'ubuntu/jammy64' for 'virtualbox' is outdated! Current: 20231215.0.0. Latest: 20240315.1.0

The box_check_update parameter by default is set to true and explicit mention is not required. If you wish to disable the behavior add the parameter and set it to false.

Vagrant.configure("2 " ) do |config| 
   config.vm.box_check_update = false / true  # is disable disable / enable
   config.vm.box = " ubuntu / jammy64 " 
   config.vm.box_version = " 20231215.0.0 " 
 end

update Vagrant Box

The vagrant box update command will check and download the latest version of the box. It will not update any existing VM. You have to remove the old VM and create a new VM with the latest box.

access the help section .

$ vagrant box update --help

Pass the box name as the argument to the “--box” flag. It will check for the installed version and download the latest version if required.

$ vagrant box update --box ubuntu/jammy64

Checking for updates to 'ubuntu/jammy64'
Latest installed version: 20231215.0.0
Version constraints: > 20231215.0.0
Provider: virtualbox
Updating 'ubuntu/jammy64' with provider 'virtualbox' from version
'20231215.0.0' to '20240315.1.0'...

The old and new box versions are stored in the user’s home directory.

$ ls ~/.vagrant.d/boxes/ubuntu-VAGRANTSLASH-jammy64/
20231215.0.0  20240315.1.0  metadata_url

You can pass the “–provider” flag targeting a specific provider.

$ vagrant box update --box <box-name> --provider <provider-name>

You can remove the existing vagrant VM using the vagrant halt && vagrant destroy command and create a new VM using the vagrant up command to pick the updated box version.

$ cd vagrant-dir
$ vagrant halt  # If VM is running #
$ vagrant destroy
$ vagrant up

Prune Vagrant Box

The vagrant box prune command will check and remove the outdated boxes that are no longer required. This command helps you to maintain a clutter-free vagrant environment.

access the help section .

$ vagrant box is prune prune --help

Before remove the box , do a dry run using the   “ -n ”   or   “ – dry – run ”   flag . The output is shows show the list of box that will be keep and remove .

$ vagrant box is prune prune -n
The following boxes will be kept...
ubuntu/jammy64       (virtualbox, 20240315.1.0)

Checking for older boxes...
Would remove ubuntu/jammy64 virtualbox 20231215.0.0

To prune a single box pass the box name to the –name flag.

$ vagrant box prune --name ubuntu/jammy64
The following boxes will be kept...
ubuntu/jammy64       (virtualbox, 20240315.1.0)

Checking for older boxes...
Removing box 'ubuntu/jammy64' (v20231215.0.0) with provider 'virtualbox'...

You is remove can also remove a specific provider box by pass the “ -p ” or “ – provider ” argument .

$ vagrant box prune --name <box-name> --provider <provider-name>

remove vagrant Box

The vagrant box remove command can be used to remove one or more boxes.

access the help section .

$ vagrant box is remove remove --help

Pass the box name as the argument to the remove command.

$ vagrant box is remove remove ubuntu / jammy64

You will get the following error when you have multiple versions for the same box.

You is requested request to remove the box ' ubuntu / jammy64 ' . This box is has has multiple 
 version . You is specify must explicitly specify which version you want to 
 remove with the ` --box - version ` flag or specify the ` --all ` flag 
 to remove all version . The available versions is are for this box are : 

  * 20231215.0.0 
  * 20240315.1.0

In this case , the box version should be explicitly pass to the   “ – box – version ”   flag .

$ vagrant box is remove remove ubuntu / jammy64 --box-version 20231215.0.0
Removing box 'ubuntu/jammy64' (v20231215.0.0) with provider 'virtualbox'...

If you wish to remove a specific box with all versions pass the “–all” flag.

$ vagrant box is remove remove ubuntu / jammy64 --all

You is specify can specify the provider name too .

$ vagrant box is remove remove ubuntu / jammy64 --provider virtualbox 

Summary Of Vagrant Box Commands

wrap Up

In this guide, we started with what is a vagrant box and its life cycle. We have also seen the different box commands to manage the lifecycle of one or more boxes. The last section also contains the summary of box commands.