Skip to content

How To Housekeep Your Vagrant Boxes

Photo by cottonbro from Pexels


Vagrant is a great tool for creating your development infrastructure very quickly with an easy workflow. You can create your local development (or test or production) virtual machine environment with a single vagrant up command. In Vagrant Virtual Machine images are distributed as boxes (like VM templates in VMWare or images in public cloud) and will be fetched from the Vagrant Cloud.

Also read : How to create an Ansible lab using Vagrant ?

Why should I housekeep Vagrant Boxes ?

If you are using different Operating systems and virtual machines using Vagrant, there will be multiple Vagrant boxes downloaded on your local machine and indeed it will take a lot of space.  Every time when you execute a vagrant up (for a new virtual machine), Vagrant will check if the box is already available on the local machine. If the box is not available, Vagrant will try to download the box from Vagrant cloud automatically. If you are not using those boxes, it is recommended to delete those boxes and save the space.

How to find the Vagrant boxes available on the local machine ?

You don’t need to find and delete the Vagrant boxes from directories. vagrant box utility will help you to manage the boxes on your local machine. We can see the available options by executing vagrant box command and the options are self-explanatory.

$ vagrant box     
Usage: vagrant box <subcommand> [<args>]

Available subcommands:

For help on any individual subcommand run `vagrant box <subcommand> -h`
        --[no-]color                 Enable or disable color output
        --machine-readable           Enable machine readable output
    -v, --version                    Display Vagrant version
        --debug                      Enable debug output
        --timestamp                  Enable timestamps on log output
        --debug-timestamp            Enable debug output with timestamps
        --no-tty                     Enable non-interactive output

Read : Creating a Kubernetes Cluster using Vagrant and Ansible

List Vagrant boxes

vagrant box list command will show the existing Vagrant boxes on the local machine.

$ vagrant box list
ansible/tower                                (virtualbox, 3.7.2)
bento/ubuntu-16.04                           (virtualbox, 202007.17.0)
cb-training-pipeline-fundamentals-1588693109 (virtualbox, 0)
centos/7                                     (virtualbox, 2004.01)
centos/8                                     (virtualbox, 2011.0)
generic/rhel7                                (virtualbox, 3.1.22)
generic/rhel8                                (virtualbox, 3.4.0)
generic/ubuntu1804                           (virtualbox, 3.1.6)
google/gce                                   (google, 0.1.0)
hashicorp/bionic64                           (virtualbox, 1.0.282)
laravel/homestead                            (virtualbox, 9.4.0)
ubuntu/bionic64                              (virtualbox, 20191125.0.0)
ubuntu/xenial64                              (virtualbox, 20200729.0.0)

I can see a lot of similar, unused and old boxes there which I am not using anymore.

How to delete  a Vagrant box

Deleting a Vagrant box is simple and straightforward as shown below.

$ vagrant box remove generic/ubuntu1804
Removing box 'generic/ubuntu1804' (v3.1.6) with provider 'virtualbox'...

# deleting one more box
$ vagrant box remove ansible/tower
Removing box 'ansible/tower' (v3.7.2) with provider 'virtualbox'...

That’s it, the box and related files will be deleted from the local machine.

Handling multiple versions of same Vagrant Boxes

When you have multiple vagrant boxes for same image you need to explicitly mention the version of the box you want to delete.

$ vagrant box list |grep rhel7          
generic/rhel7                                (virtualbox, 3.1.22)
generic/rhel7                                (virtualbox, 3.4.2)

Let’s try to delete with simple command.

$ vagrant box remove generic/rhel7     
You requested to remove the box 'generic/rhel7' with provider
'virtualbox'. This box has multiple versions. You must
explicitly specify which version you want to remove with
the `--box-version` flag or specify the `--all` flag to remove all
versions. The available versions for this box are:

 * 3.1.22
 * 3.4.2

See, vagrant cannot decide which version to be deleted and asking you to provide the version information using --box-version.

$ vagrant box remove generic/rhel7 --box-version 3.1.22
Removing box 'generic/rhel7' (v3.1.22) with provider 'virtualbox'...

What if vagrant box command not really working ?

There might be situations where vagrant box command responds with error due to file error or wrong permissions etc. Do not need to worry as you can still clean up your unwanted boxes manually.

Vagrant will save the boxes under the .vagrant.d directory inside your home directory.

$ cd ~/.vagrant.d 
$ pwd

We can see the boxes in an organised structure under the directory box.

$ ls -l boxes 
total 0
drwxr-xr-x  4 gini  staff  128 29 Jul  2020 bento-VAGRANTSLASH-ubuntu-16.04
drwxr-xr-x  3 gini  staff   96 30 Mar 12:00 cb-training-pipeline-fundamentals-1588693109
drwxr-xr-x  4 gini  staff  128  1 Aug  2020 centos-VAGRANTSLASH-7
drwxr-xr-x  4 gini  staff  128  3 Mar 22:56 centos-VAGRANTSLASH-8
drwxr-xr-x  4 gini  staff  128 12 Jan  2021 generic-VAGRANTSLASH-rhel7
drwxr-xr-x  4 gini  staff  128 27 Aug 15:46 generic-VAGRANTSLASH-rhel8
drwxr-xr-x  4 gini  staff  128  7 Jun  2019 google-VAGRANTSLASH-gce
drwxr-xr-x  4 gini  staff  128  9 Apr 01:20 hashicorp-VAGRANTSLASH-bionic64
drwxr-xr-x  4 gini  staff  128 27 Mar  2020 laravel-VAGRANTSLASH-homestead
drwxr-xr-x  4 gini  staff  128  1 Dec  2019 ubuntu-VAGRANTSLASH-bionic64
drwxr-xr-x  4 gini  staff  128  1 Aug  2020 ubuntu-VAGRANTSLASH-xenial64

And simply delete the respective direcrory.

$ rm -rf bento-VAGRANTSLASH-ubuntu-16.04

Wrap up

vagrant box utility will be very useful when you are working with several virtual machines and boxes using Vagrant. And as a best practice, observe your Vagrant boxes and do regular housekeeping as needed.

Disclaimer: The views expressed and the content shared are those of the author and do not reflect the views of the author's employer or techbeatly platform.

Gineesh has worked as a Systems Engineer, Automation Specialist, and content author. His primary focus is on Ansible Automation, Containerisation (OpenShift & Kubernetes), and Infrastructure as Code (Terraform). (aka Gini Gangadharan -


Leave a Reply

Your email address will not be published.

This site uses Akismet to reduce spam. Learn how your comment data is processed.