Getting Started With Homestead

Recently I needed to get to grips with the Laravel PHP framework for a personal project and thought a small tutorial on getting started with the Homestead development environment would be good to help beginners.


You’ll need the following:

  • macOS or Linux
  • Latest version of Oracle’s VirtualBox
  • Latest version of Vagrant from Hashicorp
  • (optional) Latest version of Composer

Installing Homestead

Start by installing the Homestead Vagrant box on your machine by running the following command from a shell prompt:

vagrant box add laravel/homestead

While you can install the box at the time you run vagrant up, we’re starting the download now so it can run in the background while we complete some other tasks.

Next clone the Homestead repository from GitHub:

git clone
cd homestead
git checkout v7.20.0

You’ll notice we also checked out a specific tagged commit, this is because the master branch can be unstable and doesn’t have the same rigorous testing applied as tagged releases.

Next we run the initialisation script:

chmod +x

Next up we have to configure the newly created Homestead.yaml file. Open it in your editor of choice and underneath folders change ~/code to the location where you’ll put your Laravel project, such as ~/Projects/contacts. You’ll need to replace the location of the code as well, so it becomes /home/vagrant/contacts in this example. Then below that in sites, map your site name, such as contacts.test to the above specified folder, like /home/vagrant/contacts/public.

Now if your Vagrant box has finished downloading from earlier you can run vagrant up to bring your new Homestead development environment up and get ready to work on your Laravel project. Keep in mind you don’t have to use this for Laravel, Homestead contains a number of languages, frameworks, and databases to allow you to build a lot of different systems.

Getting DNS Working

To get that URL that you selected working with Homestead, you’ll need to set it up in your hosts file. To do that, edit the file at /etc/hosts and add a line like the following:


Keen observers will notice the IP address is copied from the top of the Homestead.yaml file, if you do change that make sure to update it in your hosts file.

You should now be able to the example site at http://contacts.test and see “No input file specified.".

(Optional) Starting With Laravel

Run the following Composer command to install your new site (replace ~/Projects/contacts with your project location):

composer create-project --prefer-dist laravel/laravel ~/Projects/contacts
cd ~/Projects/contacts

Now you’ll be able to view your default Laravel site at your URL and be presented with a splash page.