Skip to content
Tutorials Center
My learning

Topics

Lesson 7 of 36 ยท Vagrantfile and Boxes

Managing Boxes

Manage Vagrant boxes from the command line: add, list, outdated, update, prune and remove, plus how versions, providers and disk space work.

Boxes are large: a typical Linux box is 400 MB to 1.5 GB and unpacks to several gigabytes. They are stored once per computer and shared by every project, so a little housekeeping goes a long way. The vagrant box command family lets you download boxes ahead of time, see what you have, update them, and reclaim disk space.

Adding a box

Normally vagrant up adds a missing box automatically. You can also do it explicitly, for example before a trip or a workshop when you want everything cached:

CONSOLE
$ vagrant box add bento/ubuntu-24.04 --provider virtualbox
==> box: Loading metadata for box 'bento/ubuntu-24.04'
    box: URL: https://vagrantcloud.com/api/v2/vagrant/bento/ubuntu-24.04
==> box: Adding box 'bento/ubuntu-24.04' (v202508.03.0) for provider: virtualbox
    box: Downloading: https://vagrantcloud.com/...
==> box: Successfully added box 'bento/ubuntu-24.04' (v202508.03.0) for 'virtualbox'!

Useful options:

Option Purpose
--provider NAME Choose the provider variant instead of being asked
--box-version VERSION Add a specific version or constraint
--name NAME Store the box under a local name (for file or URL boxes)
--checksum VALUE and --checksum-type sha256 Verify the download
--force Overwrite an existing box of the same name, version and provider
--insecure Skip TLS verification (avoid it)

You can add a box from a file or URL and give it a short name that your Vagrantfile then uses:

CONSOLE
$ vagrant box add --name company/ubuntu-base ./ubuntu-base.box
Ruby
Vagrant.configure("2") do |config|
  config.vm.box = "company/ubuntu-base"
end

Listing and inspecting

CONSOLE
$ vagrant box list
bento/ubuntu-24.04 (virtualbox, 202508.03.0)
bento/debian-12    (virtualbox, 202407.22.0)
bento/debian-12    (virtualbox, 202502.21.0)
ubuntu/jammy64     (virtualbox, 20240201.0.0)

Each line shows the box name, the provider and the version. A box can exist in several versions at once; a project uses the version its Vagrantfile selects. To see more, vagrant box list -i adds extra information such as the box's metadata description.

Finding out about updates

Vagrant does not change a box that is already downloaded. When a project starts, it checks for updates (unless config.vm.box_check_update = false) and prints a notice, but keeps using the old version. To see updates for the current project's box:

CONSOLE
$ vagrant box outdated
Checking if box 'bento/ubuntu-24.04' version '202508.03.0' is up to date...
A newer version of the box 'bento/ubuntu-24.04' for provider 'virtualbox' is
available! You currently have version '202508.03.0'. The latest is version
'202509.10.0'. Run `vagrant box update` to update.

To see updates for all boxes on your machine, use vagrant box outdated --global.

Updating

CONSOLE
$ vagrant box update
$ vagrant box update --box bento/debian-12 --provider virtualbox

Updating downloads a new version next to the old one. It does not change machines that already exist. To benefit from the new base image you must rebuild the machine:

CONSOLE
$ vagrant destroy -f
$ vagrant up

If you pinned config.vm.box_version, vagrant box update still adds newer versions, but your project keeps using the pinned one until you change the Vagrantfile. This is exactly the behavior you want in a team: updates are a deliberate edit of the Vagrantfile, reviewed in a pull request.

flowchart LR
    A["vagrant box outdated"] --> B{"newer version?"}
    B -- no --> C["done"]
    B -- yes --> D["vagrant box update"]
    D --> E["new version cached next to the old"]
    E --> F["edit box_version in Vagrantfile"]
    F --> G["vagrant destroy && vagrant up"]
    G --> H["VM built from new base"]

Boxes are updated deliberately: download, pin, rebuild.

Removing and pruning

Old versions pile up. Remove a specific one:

CONSOLE
$ vagrant box remove bento/debian-12 --box-version 202407.22.0
Removing box 'bento/debian-12' (v202407.22.0) with provider 'virtualbox'...

If machines still use that version, Vagrant refuses; add --force only when you know those machines are disposable. To delete all old versions in one go, keep only the newest of each box:

CONSOLE
$ vagrant box prune
$ vagrant box prune --dry-run     # show what would be removed
$ vagrant box prune --keep-active-boxes

--keep-active-boxes protects the versions that running or existing machines depend on. Check the used disk space first: boxes live in ~/.vagrant.d/boxes and you can inspect them with your system's disk tools. If the system drive is tight, move the Vagrant home with the VAGRANT_HOME environment variable before adding boxes.

Understanding versions in a model

Box listings are sorted by version, and a pinned constraint picks the newest match. The runnable stand-in below mimics vagrant box list, outdated and prune on an in-memory inventory so you can see the logic without downloading anything. It is a Ruby stand-in, not Vagrant.

Ruby Box inventory: outdated and prune (stand-in)

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with gets), it gets the next line from this box.

Sharing boxes with a team

For a small team, the easy way is a shared folder or web server with a .box file and a JSON metadata file listing versions and URLs. Vagrant Cloud also offers private boxes for organizations. Whichever you choose, record the box source in the project README or directly in the Vagrantfile (box_url), so a newcomer never has to ask where the file comes from.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. What does vagrant box update do to a machine that already exists?

    Updating only fetches the new version into the cache. Existing VMs keep their disk until you rebuild.
  2. 2. Which command lists every cached box and its version?

    vagrant box list shows name, provider and version for each cached box.
  3. 3. How do you reclaim disk space from old box versions safely?

    prune removes outdated versions; --dry-run shows what would go, and --keep-active-boxes protects boxes in use.
  4. 4. Why is pinning box_version useful when you run vagrant box update?

    Newer versions may be downloaded, but the pinned version is what machines of that project use.

Summary

  • vagrant box add/list/outdated/update/remove/prune manage the global box cache.
  • Updates download a new version beside the old one; rebuild the machine to use it.
  • Pin versions in the Vagrantfile so base image changes are deliberate.
  • Use prune --dry-run and VAGRANT_HOME to control disk space.

Next: VM Settings and Resources