// Tutorial //

How to Create a Vagrant Base Box from an Existing One

Draft updated on Invalid Date
    Default avatar

    By Nicholas Cerminara

    How to Create a Vagrant Base Box from an Existing One

    This tutorial is out of date and no longer maintained.


    Vagrant Boxes are prepackaged development environments that are the foundation of Vagrant. In most cases, this is usually just a stripped and naked operating system such as Ubuntu, Debian, or CentOS. Boxes exist with the intention to be provisioned with additional features like Apache and PHP using tools like Chef or Puppet. This is really powerful, but it can be time-consuming to set up the first configuration and difficult for beginners. Plus, not everyone has the skill set of a system admin or works with a huge collaborative team.

    This post will describe to you how to create your own prepackaged Vagrant Box from an existing virtual machine. In my opinion, it’s the quickest and easiest way for beginners to get started with Vagrant. This way you’ll be able to reuse it over and over and even share it. I feel this generally goes against the main idea of Vagrant where you provision your development environments from a single config. You generally lose a lot of the debugging and configurability of your development environment, but this should be helpful for plenty of developers, teams, and projects regardless.

    Choose a Box

    The first thing you’ll need to do is pick a box that you want to build from. The Vagrant Cloud lets you easily find boxes that people have shared. We’ll be working off of Hashicorp’s (Vagrant’s) Precise64. This box is a good one to work off of because Chef and Puppet are already installed, plus all the settings we’re configured by the creator(s) of Vagrant.

    Initialize and Start the Vagrant Box

    After you’ve chosen a box, initialize the Vagrant box. Each one is slightly different, but here’s how to do it for the example we’re doing:

    1. vagrant init hashicorp/precise64

    This will also create a Vagrant file for you. Now, boot the box with Vagrant by doing (it will need to download if it’s the first time using it):

    1. vagrant up

    SSH into the Box and Customize It

    We’ll now SSH into the box and start customizing it. Here’s how to SSH into the box:

    1. vagrant ssh

    Now, we need to set up our server by installing whatever we want on it. This example will install a basic LAMP stack, but you can do whatever you like (Ruby, Nginx, etc.). The point of this article isn’t to teach you how to set up a server, but instead how to turn your virtual environment into a Vagrant Box. So this step might be more involved than what is actually shown:

    1. sudo apt-get update
    2. sudo apt-get upgrade
    3. sudo apt-get install vim
    4. sudo apt-get install apache2
    5. sudo apt-get install mysql-server libapache2-mod-auth-mysql php5-mysql
    6. sudo mysql_install_db
    7. sudo /usr/bin/mysql_secure_installation
    8. sudo apt-get install php5 libapache2-mod-php5 php5-mcrypt
    9. sudo apt-get install php5-cgi php5-cli php5-curl php5-common php5-gd php5-mysql
    10. sudo service apache2 restart

    Make the Box as Small as possible

    We’re now going to clean up disk space on the VM so when we package it into a new Vagrant box, it’s as clean as possible. First, remove APT cache

    1. sudo apt-get clean

    Then, “zero out” the drive (this is for Ubuntu):

    1. sudo dd if=/dev/zero of=/EMPTY bs=1M
    2. sudo rm -f /EMPTY

    Lastly, let’s clear the Bash History and exit the VM:

    1. cat /dev/null > ~/.bash_history && history -c && exit

    Repackage the VM into a New Vagrant Box

    We’re now going to repackage the server we just created into a new Vagrant Base Box. It’s very easy with Vagrant:

    1. vagrant package --output mynew.box

    Add the Box into Your Vagrant Install

    The previous command will have created a “mynew.box” file. You can technically put this wherever you want on your computer. Now, let’s add this new Vagrant Box into Vagrant:

    vagrant box add mynewbox mynew.box

    This now will “download” the box into your Vagrant install allowing to initiate this from any folder, but before we do this, let’s delete and remove the Vagrant file we built this box from.

    1. vagrant destroy
    2. rm Vagrantfile

    Initialize Your New Vagrant Box

    We need to now initialize a Vagrant environment from our brand new box using the same command from earlier but referencing the new Box.

    1. vagrant init mynewbox

    Customize Your New Vagrantfile

    When you initialize the Vagrant environment, it creates a Vagrantfile for you (just like from before). Open the Vagrantfile and delete everything. You can use what was in there as a reference or just use Vagrant’s Official Docs, but we’re going to only use the absolute essentials that I’ve already spelled out for you.

    Now paste the following bare-bones code into your Vagrantfile:

    Now let’s create a landing page:

    1. vim index.php

    And add the following line to demo what we just installed with PHP:


    Visit Your Site!

    Now, visit the IP address from the Vagrantfile in your browser. If everything works, you should see a PHP info dump of the index.php file you just created.


    Now that you’ve just created your own Vagrant Base Box from an existing one, you should consider sharing it on the Vagrant Cloud. This way other people can download and use it!

    There are tons of ways of building Vagrant Boxes, and this method is only intended to get you started in the easiest and fastest way. You should consider these additional resources if you want to build from scratch or use a service to help you with the process:

    Thanks for learning with the DigitalOcean Community. Check out our offerings for compute, storage, networking, and managed databases.

    Learn more about us

    About the authors
    Default avatar
    Nicholas Cerminara


    Still looking for an answer?

    Ask a questionSearch for more help

    Was this helpful?
    Leave a comment

    This textbox defaults to using Markdown to format your answer.

    You can type !ref in this text area to quickly search our full set of tutorials, documentation & marketplace offerings and insert the link!

    Try DigitalOcean for free

    Click below to sign up and get $200 of credit to try our products over 60 days!

    Sign up

    card icon
    Get our biweekly newsletter

    Sign up for Infrastructure as a Newsletter.

    Sign up
    card icon
    Hollie's Hub for Good

    Working on improving health and education, reducing inequality, and spurring economic growth? We’d like to help.

    Learn more
    card icon
    Become a contributor

    You get paid; we donate to tech nonprofits.

    Learn more
    Welcome to the developer cloud

    DigitalOcean makes it simple to launch in the cloud and scale up as you grow – whether you’re running one virtual machine or ten thousand.

    Learn more ->
    DigitalOcean Cloud Control Panel
    Get started for free

    Enter your email to get $200 in credit for your first 60 days with DigitalOcean.

    New accounts only. By submitting your email you agree to our Privacy Policy.