How to setup Laravel Homestead in Windows

17. March 2017 PHP 8

Developing with PHP under Windows can be a real pain. Sure there are applications like WAMP or XAMPP that include the stack you need, but in the end you are not emulating the environment where your live application is very likely to run: Linux.

Laravel Homestead is a great tool to setup your PHP development environment, but it can be a little confusing to configure and slow in Windows. But fear not, in this tutorial you’ll learn how to setup Laravel homestead for your PHP projects.

Installing the software

The first thing to do is download and install the following software:

  • VirtualBox for Windows 5.1.14 – this is what manages and helps emulate a guest OS (Linux, in our case) inside a host OS (Windows). I recommend this particular version because newer ones would have problems with folder synchronization.
  • Vagrant installer for Windows – this is a command line tool that runs on top of virtualization software such as VirtualBox or VMWare. It also gives us some other nice features like file sync between our guest and host OS.
  • Git for Windows – we will need this so we can clone the Laravel Homestead repository from Github, but more important, it comes with a terminal emulator which will come in handy.
Note: be sure to install VirtualBox first, since Vagrant depends on it.

Adjusting VirtualBox and Vagrant

The next step is to make some tweaks to VirtualBox and Vagrant. We need to do this because, by default, both tools store data in the same drive where they were installed (tipically the C drive). The thing with virtual machines is they can take up a lot of space, so they can eat up your main drive’s storage very quickly.

First we’ll change the storage path in Virtual Box, since it’s pretty straightforward. You now should have a program called Oracle VM VirtualBox installed. Open it and then go to File > Preferences. A new dialog will open where you can change the folder next to the option that reads Default Machine Folder. Click the dropdown and choose Other…. Here you can choose the new folder for VirtualBox to store data. For example, I have a partition called D and I chose a path on that drive.

Now we’ll do the same for Vagrant. By default the path where data related to virtual machines is stored is C:\Users\YourUser\.vagrant.d so I recommend changing it to a different drive. This can be done with environment variables. We need to create a variable called VAGRANT_HOME and point it to our desired location.

Open the control panel and search for the word environment. From the results choose the one that says edit environment variables for your account.

On the new dialog that appears, click the New… button.

Here you will create the new variable. Enter VAGRANT_HOME as the value for the field named Variable name. For the field named Variable value enter the path of your choice. In my case I used the path D:\VM\Vagrant

Click OK in both New User Variable and Environment Variables dialogs to save changes.

Getting the Homestead image

Ok, so now we have the basic blocks for our setup, so what role Homestead plays then? Well, VirtualBox and Vagrant allows us to emulate the environment, but we can say these tools only manage and run the virtual machine. We still need an image of the machine and something that installs the required tools so that we don’t have to it manually. That’s where Homestead comes in!

First we need to download the OS for the guest machine. Laravel homestead already has an image for this. The latest version at this time comes with Ubuntu 16.04. To install it open Git Bash (the terminal emulator that comes with Git for Windows) and execute the following command:

This will show the following message asking you to choose your virtualization provider. Enter the number that corresponds to VirtualBox and press Enter:

The OS will start downloading. This can take some minutes depending on your internet connection. Once it finishes downloading a message will appear saying the box was successfully added.

Getting the Homestead repository

So we have the guest OS, but it doesn’t have PHP or a webserver installed. For that we need the Homestead repository, which has the config files and scripts that take care of those things.

Open Git Bash and cd into a directory of your choice (tipically your home directory) and clone the Homestead repository:

Now cd into the newly created Homestead directory and initialize the homestead config:

This will create a configuration file called Homestead.yaml in this directory. We’ll get back to this file shortly.

Creating a SSH key

Thanks to Vagrant folder synchronization we’ll be able to edit our project files in the host machine (Windows) and they will be reflected into the guest machine. But for other tasks such as running migrations and other commands it will be necessary to log into the guest via the terminal. For this we’ll need a SSH key. If you already have one or more you can skip this step.

Once again, Git Bash will ease things for us in Windows. Instead of using a program to create a key and another one to connect to the guest, we can do all that with this terminal emulator.

To create a new SSH key enter the following command:

A message like this will appear

And then a prompt for a path to store the new key. Simply hit Enter:

Then you will be asked for a passphrase twice. This is recommended for security purposes, but for local development you can leave it empty and just hit Enter both times:

Configuring folders and sites

You should have now a file called Homestead.yaml inside your Homestead folder. This file should like this:

Let’s see what these settings mean:

  • ip: the local ip address the virtual machine will respond to. This ip should be used in your hosts file since sites configured in Homestead are served from the virtual machine, instead from the host machine loopback ip (
  • memory: amount of RAM in megabytes available for the virtual machine. By default set to 2 GB.
  • cpus: number of processors on the virtual machine.
  • provider: the virtualization system to use. By default configured already for VirtualBox.
  • authorize: location of our SSH public key. The tilde (~) shortcut to point to our user’s home folder is recognized here as well.
  • keys: here we specify the path of the private SSH key. Tipically the same name as the public key but without the .pub extension.
  • folders: this is where we specify which folders in Windows should be synchronized with the virtual machine. - map is tipically the folder where you have or will have your application code; Homestead by default points to a folder called Code in your home directory, but you can change it if you need to. The important thing here is that this folder won’t be created for you, so if this will be a new folder, you have to create it first. to is the path where the contents of - map will be copied to. This folder will be created automatically in the virtual machine.
  • sites: this is where you will map the domains of each application you want to run with Homestead. Each site should have its own - map and to options where - map should contain the name of the domain and to should point to the site’s root folder in the virtual machine. By default, Homestead has a domain named that points to /home/vagrant/Code/Laravel/public. An important thing to note is that the root of your sites must be a sub-folder of the path you configured in the folders section. For example, if you configured a path in the virtual machine at /home/vagrant/Code, your sites’ root must be inside /home/vagrant/Code
  • databases: the list of MySQL databases you want Homestead to create when it boots.

This is an example of how the folders, sites and databases sections of our configuration file may look:

In this case, the code in the host Windows machine is in a folder called Projects which is located at the user’s home folder. The Projects folder contents will be synchronized to the virtual machine to a folder located at /home/vagrant/Code. We have two sites: and; we can see they both point to a subfolder within /home/vagrant/Code/. We have also listed two databases to create: one_db and another_db.

Booting the virtual machine

To boot the virtual machine, cd into the Homestead folder and execute the following command:

The virtual machine will start booting and configuring. This should take some seconds.

Connecting to the virtual machine

Once the virtual machine has booted you can ssh into by simply running the following inside your Homestead folder:

You should be shown something like the following, which means you are now inside the virtual machine:

From here you can for example connect to MySQL to manage your databases. The user for the MySQL installation is homestead and the password is secret.

Another way of managing databases is using a GUI application. I’ll show you a nice app for Windows called HeidiSQL and how to connect from Windows to the MySQL server in Homestead.

If you logged into MySQL in the terminal, enter the exit command to quit MySQL and then again to logout from the virtual machine:

Connecting to MySQL with HeidiSQL

The first thing to do is to get the installer of HeidiSQL. Get it, install it and open the application. You should be presented with a screen like this:

On this screen we’ll configure the connection to MySQL. Click the New button and follow these steps:

  1. enter a description for the connection
  2. enter the connection credentials
    • user: homestead
    • password: secret
    • port: 33060
  3. click Save
  4. click Open

A new window like this will show, the list of databases will differ since I have created some other ones.

Adding a new Laravel site

The virtual machine is running and has the tools installed for us to work. We’ll now setup a new Laravel project. First we need to add the site to the sites section of the Homestead.yaml file. Let’s call this site and add a new database as well called mylaravelapp:

Now we need to reload the virtual machine and pass a flag so that it “refreshes” the list of sites and databases and can pick up our new added site. Execute this command, make sure you are inside your Homestead directory:

The virtual machine will reboot and create the new database and add a new nginx site called

Once the virtual machine has finished booting, ssh into the machine, go to the shared Code folder and create a new Laravel project with Composer:

This will clone the Laravel repository and will begin installing Composer dependencies. This will install the latest Laravel version, which at the time of writing is 5.4:

Composer may take a while depending on your internet connection. Once the installation finishes we need to open our Windows hosts file located at C:\Windows\System32\drivers\etc\hosts and add the following:

It’s very likely that you need to open the file with Administrator privileges. I open it with notepad but I use Run as Admnistrator. Also note that the ip must match the one configured in the Homestead.yaml file

Save the hosts file, open your browser and go to You should be presented with the Laravel welcome page:

Speeding things up

Even if the Laravel application is showing the welcome page, it’s very possible that you notice the page doesn’t load as fast as in a local webserver. This is a problem with Homestead that for some time we just had to deal with, the good thing is there is a plugin for Vagrant that will allow us to use NFS (network file system) on Windows (even when the Vagrant site says it’s simply not supported).

To install the plugin simply execute the following command in Git Bash:

The plugin should take a couple of seconds to install.

Now there’s only small change we need to do in Homestead.yaml to enable NFS. Add the following to the folders section in the file:

Finally, re-provision the virtual machine so that it picks up the new options:

And that’s it, you should notice faster page loads now.

Notice that when connecting to MySQL from HeidiSQL we used port 33060, this is because Homestead redirects some of the ports. We did this when connecting from the host machine, but any configuration in your .env file should use the standard port for MySQL 3306 because your application runs inside the virtual machine, the same goes for the MySQL host, it would use the loopback ip

And that’s how we reach the end of the tutorial. I really hope you find it useful for setting up a development environment for PHP.