To download or upgrade a Vagrant box, you can use the command vagrant box add and vagrant box update.

Most of the time, you should be fine using these automated processes. But sometimes you need more control. Imagine you are working from home and you need to download several huge boxes. You also have video calls with your customers throughout the day, so your priority is to maintain high call quality. To do that, you need to prevent Vagrant from eating up your entire internet bandwidth.

Control your Vagrant download

Vagrant has no built-in option for controlling the download process, but fortunately, you can use the tool of your choice to download a box.

You also want to integrate a box smoothly into your existing Vagrant environment so that commands like vagrant box update will work as intended.

In the following example, we will download and import the Debian Buster v10.7.0 box for Virtualbox.

To download a box

  1. Get the direct download link for a box.

  2. Download the box.

    I am using curl here with a download rate limit, but you can use any tool that works for you.

    $ curl --location --remote-name --limit-rate 500k --continue-at - https://app.vagrantup.com/debian/boxes/contrib-buster64/versions/10.7.0/providers/virtualbox.box

To import a box

  1. Add the box to Vagrant.

    Note the last argument, which is the local file you just downloaded.

    $ vagrant box add debian/contrib-buster64 ./virtualbox.box

  2. Rename the version directory of the box to the correct version.

    $ cd ~/.vagrant.d/boxes/debian-VAGRANTSLASH-buster64/
$ mv ./0 ./10.7.0

    Your directory structure should now look like this:

    debian-VAGRANTSLASH-contrib-buster64/
| 10.7.0/
| | virtualbox/
| | | Vagrantfile
| | | box.ovf
| | | box_update_check
| | | contrib-buster.vmdk
| | | master_id
| | | metadata.json
| metadata_url

  3. If not exist, create a metadata_url file.

    This file should contain a link to the Vagrant box without the version part.

    $ echo -n "https://app.vagrantup.com/debian/boxes/contrib-buster64" > ./metadata_url

  4. Verify by listing all installed boxes.

    $ vagrant box list
debian/contrib-buster64  (virtualbox, 10.7.0)

You should see your new or updated box with the correct version number and, commands like vagrant box update should work as usual.