mirror of
https://github.com/hashicorp/vagrant.git
synced 2026-02-03 20:39:27 -05:00
78 lines
3.8 KiB
Text
78 lines
3.8 KiB
Text
---
|
|
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.
|
|
---
|
|
|
|
# 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.
|
|
|