---
layout: docs
page_title: Vagrant Boxes
description: |-
  Boxes are the package format for Vagrant environments. A box can be used by
  anyone on any platform that Vagrant supports to bring up an identical
  working environment.
---

⚠️⚠️⚠️⚠️⚠️⚠️⚠️⚠️⚠️⚠️⚠️⚠️
> [!IMPORTANT]  
> **Documentation Update:** Product documentation previously located in `/website` has moved to the [`hashicorp/web-unified-docs`](https://github.com/hashicorp/web-unified-docs) repository, where all product documentation is now centralized. Please make contributions directly to `web-unified-docs`, since changes to `/website` in this repository will not appear on developer.hashicorp.com.
⚠️⚠️⚠️⚠️⚠️⚠️⚠️⚠️⚠️⚠️⚠️⚠️

# Vagrant boxes

Boxes are the package format for Vagrant environments. You specify a box environment and operating configurations in your [Vagrantfile](/vagrant/docs/vagrantfile). You can use a box on any [supported platform](/vagrant/downloads) to bring up identical working environments. To enable teams to use and manage the same boxes, [versions are supported](/vagrant/docs/boxes/versioning). 

~> **Note**: Boxes require a provider, a virtualization product, to operate. Before you can use a box, 
ensure that you have properly installed a supported [provider](/vagrant/docs/providers).

The quickest way to get started is to select a pre-defined box environment from the
[publicly available catalog on Vagrant Cloud](https://vagrantcloud.com/boxes/search).
You can also add and share your own customized boxes on Vagrant Cloud.

The `vagrant box` CLI utility provides all the functionality for box management. You can read the documentation on the [vagrant box](/vagrant/docs/cli/box)
command for more information.

## Discover boxes

To find boxes, explore the
[public Vagrant box catalog](https://vagrantcloud.com/boxes/search)
for a box that matches your use case. The catalog contains most major operating
systems as bases, as well as specialized boxes to get you started with common 
configurations such as LAMP stacks, Ruby, and Python.

The boxes on the public catalog work with many different
[providers](/vagrant/docs/providers/). The list of supported providers is located in the box descriptions.  

### Add a box 

You can add a box from the public catalog at any time. The box's description includes instructions
on how to add it to an existing Vagrantfile or initiate it as a new environment on the command-line.

A common misconception is
that a namespace like "ubuntu" represents the official space for Ubuntu boxes.
This is untrue. Namespaces on Vagrant Cloud behave very similarly to namespaces on
GitHub. Just as GitHub's support team is unable to assist with
issues in someone's repository, HashiCorp's support team is unable to assist
with third-party published boxes.

## Official boxes

There are only two officially-recommended box sets.

HashiCorp publishes a basic Ubuntu 18.04 64-bit box that is available for minimal use cases. It is highly optimized, small in size, and includes support for VirtualBox, Hyper-V, and VMware. 

To get started, use the `init` command to initialize your environment. 

```shell-session
$ vagrant init hashicorp/bionic64
```

If you have an existing Vagrantfile, add `hashicorp/bionic64`. 

```ruby
Vagrant.configure("2") do |config|
  config.vm.box = "hashicorp/bionic64"
end
```

For other base operating system environments, we recommend the [Bento boxes](https://vagrantcloud.com/bento). The Bento boxes are [open source](https://github.com/chef/bento) and built for a number of providers including VMware, VirtualBox, and Parallels. There are a variety of operating systems and versions available.

Special thanks to the Bento project for providing a solid base template for the `hashicorp/bionic64` box.

It is often a point of confusion but Canonical, the company that makes the Ubuntu operating system, publishes boxes under the "ubuntu" namespace on Vagrant Cloud. These boxes only support VirtualBox.

## Create a box

If you are unable to find a box that meets your specific use case, you can create one. We recommend that you first create a [base box](/vagrant/docs/boxes/base) to have a clean slate to start from when you build future development environments.

Learn more about [box formats](/vagrant/docs/boxes/format) to get started. 

