March 08, 2015

Posted by Sherri Flemings | File under : , , , , , ,
Install Laravel Homestead 2.0 on Windows
I've tried to set up Laravel's Homestead on Windows a few times before. Until now I always gave up because I just ran out of time trying to troubleshoot one error after another on both of my Windows machines. The Homestead setup guide and Laracast videos make it look so freaking easy, but they are not targeting Windows users so it sometimes becomes a very frustrating experience for us... and usually ends with reverting back to your XAMPP or WAMP installation and a promise to try again when you have more time.

I finally had some time to try this again, and although there were a lot of steps and some annoying errors it was actually pretty easy to get going! I know there are some web devs out there who might be intimidated using a command-line, or a virtual machine and some of the error messages you get might have you feeling like you're in way over your head but I wanted to break it down here for you step by step and explain some of the errors to help you get over the initial hurdle of installing Homestead on your Windows machine.

Warning - Before you begin you should verify in your system's BIOS that Intel Virtualization Technology is enabled. It will save you some troubleshooting time if you check now before you get started.

My goal is to install and setup Laravel 5 and Homestead 2.0 on my Windows 8.1 machine. I will be following the same steps on the Laravel install page,  but I will change the paths for Windows and share any errors I came across.


Before we start make sure you have installed the following software:

Before you install Vagrant - Vagrant uses Ruby, and there is a known issue with Ruby and spaces in paths. My very first mistake was to change the Vagrant install location to %ProgramFiles% like a good Windows citizen and that was a spectacular failure. I opted to install it here on my machine: C:\Tools\Vagrant. I just do my best not to cringe when I see that clutter in the root of my system drive.

Step 1: Open Git Bash

I highly recommend that you use Git Bash as your command-line for the following steps since it will allow us to enter the same commands in the docs without having to manually edit files. If you are also planning to install the vagrant hostsupdater plugin, make sure you open Git Bash as an administrator:

Step 2: Add Vagrant Box

Verify that you have the recommended Vagrant version for Homestead which at the time of this post was Vagrant 1.6

Git Bash

$ vagrant version

Add the Laravel Homestead Box to Vagrant

Git Bash

$ vagrant box add laravel/homestead

This will take several minutes so feel free to grab a coffee or a sandwich depending on your Internet speed.

Step 3: Install HostsUpdater plugin (optional)

The hostsupdater plugin will save you from having to manually update your hosts when you add a new site to your homestead box. Since the Windows hosts file is protected you'll need to make sure you're running Git Bash as an admin (it's not really necessary to be running as admin during this step, but later when you start your homestead box).

Git Bash

$ vagrant plugin install vagrant-hostsupdater

Step 4: Install Homestead

Help: you will see references to your "home" directory, or "~" (tilde) within the Laravel docs. This is *nix vocabulary, the Windows equivalent is the user home path, or the env vars %HOMEDRIVE%%HOMEPATH%. If you are using Git Bash ~ (tilde) maps to the correct directory, however if you're using Windows cmd prompt you should use the above ENV vars to navigate to the home directory.

If you don't have PHP installed on your computer, go to Option 1, otherwise go to Option 2. I recommend Option 1 for most Windows users.

Option 1: You don't have PHP installed on your windows machine

This option assumes you have git installed and already working on your Windows machine. 

Git Bash

# ~ should take you to Windows User Home, %HOMEDRIVE%%HOMEPATH%
# typically it's C:\Users\{username}
$ cd ~
# Copy Homestead into: C:\Users\{username}\Homestead
$ git clone Homestead

Once Homestead is installed we'll create the Homestead.yaml configuration file:

Git Bash

# go to the Homestead installation directory
$ cd ~/Homestead
# initialize Homestead configuration file
$ bash

Help - if something goes wrong, or for some reason you're not using Git Bash, you can just copy the files manually. From: C:\Users\{username}\Homestead\src\stubs  to  C:\Users\{username}\.homestead

More Help - You will see references in the docs to homestead commands like homestead init, homestead edit and homestead up. These commands will not be available if you install Homestead from git (Option 1). It's not a big issue, since most of the commands are just wrapping vagrant functionality or providing a shortcut to open the Homestead configuration file in your text editor. I wanted to point this out though since there tends to be some confusion with this.

Go to Step 5

Option 2: You have PHP and Composer already installed

This option will allow you to install the Homestead CLI which provides convenience commands like homestead init or homestead up. If you already have PHP and Composer installed and working on your Windows machine this might be a good option for you, however if you don't already have them installed I strongly recommend following Option 1 above to install Homestead.

Git Bash

$ composer global require "laravel/homestead=~2.0"

To take advantage of the Homestead CLI, make sure to add the Composer /bin directory to your PATH

Help - On Windows you can find the Composer /bin inside your AppData directory: %HOMEDRIVE%%APPDATA% typically this maps to C:\Users\{username}\AppData\Roaming

Git Bash

# initialize Homestead configuration file
$ homestead init

Help - if something goes wrong, or for some reason you're not using Git Bash, you can just copy the files manually. From: C:\Users\{username}\AppData\Roaming\Composer\vendor\laravel\homestead\src\stubs  to  C:\Users\{username}\.homestead

More Help - Although I installed the Homestead CLI using Composer, I actually never use the homestead commands, instead I use the vagrant commands. I just find it less confusing since I have some other vagrant boxes setup now too.

Go to Step 5

Step 5: Generate your SSH Keys

If you are using git, you probably don't need this step. I prefer to use a different SSH key for different tools, so I'm not re-using my git keys for this step. 

My SSH client of choice is Bitvise Tunnelier, and managing keys is super easy with the Keypair Manager included with this client. You can open it by typing 'keypair' into your Windows Start Menu search, or if you have the Bitvise client open you can select the 'User keypair Manager' link on the Login tab.

Run Keypair Manager from Start Menu
Run Keypair Manager from the Bitvise SSH client

After your keys are generated, you can export your public & private keys in OpenSSH format. I exported my keys as and homestead_rsa.

Export your public and private keys to your .ssh folder

Step 6: Configure your Homestead Box

If you installed the HostsUpdater plugin, you'll need to edit the homestead.rb file  and add an aliases section to your Homestead.yaml file.


# Configure A Private Network IP
config.hostsupdater.aliases = settings["aliases"]

Configure your Homestead.yaml file for your environment. Mine looks like this :


ip: ""
memory: 2048
cpus: 1
provider: virtualbox

authorize: ~/.ssh/

    - ~/.ssh/homestead_rsa

aliases: ["", "stitchcrafter.api"]

    - map: D:\Data\Code
      to: /home/vagrant/Code

    - map:
      to: /home/vagrant/Code/Laravel/public
    - map: stitchcrafter.api
      to: /home/vagrant/Code/StitchCrafterAPI/public

    - homestead

    - key: APP_ENV
      value: local

A note about paths - You will notice that I am using the ~ (tilde) character to refer to my Windows HomePath. This should work for you and if you're sharing with a team this is the recommended approach. If you're a lone developer you can stick to hard-coded path if that's what you prefer C:\Users\{username}\.ssh

Ideally I would prefer to stick to the Windows env vars and use %HOMEDRIVE%%HOMEPATH% instead of the ~. Why? Because I don't know if ~ will also work on my Windows machines where the HomePath is not on C drive. Unfortunately Windows env vars are not currently supported.

Step 7: Launch it

So... this is where things sometimes start to unravel, hopefully I can help you get past the error messages so you can get your vagrant homestead box up and running.

A note about the different installation options - cd ~/Homestead will only work if you installed Homestead using git in your home path (Option 1). If you installed it using composer, you can call homestead up without having to be inside the Homestead folder (as long as composer\vendor\bin is part of your PATH). Otherwise you'll have to cd into that long path. In the steps below I follow the path less travelled and use the commands for a Git installation, if you installed with composer please use the commands recommended for that installation type.

Help - Some people are having trouble getting the homestead commands to work properly after installing with composer (Option 2). This is usually a result of not adding composer bin to your PATH. If you prefer to not add it to your path and you're using Git Bash you can take advantage of it and create a .bashrc file in your home path to create an alias (just change the Windows \ to / in the path)


alias hs="cd C:/Users/{Username}/AppData/Roaming/Composer/vendor/laravel/homestead"

Now you can just use the hs command to get to the Homestead directory in a composer installation (if you need to).

OK. Let's get this box up and running now...

Git Bash

$ cd ~/Homestead
$ vagrant up

First Error: The first attempt got stuck and kept repeating this error line:
Error: Connection timeout. Retrying...

I opened the VirtualBox GUI to try running the Homestead box from there. This is where I saw what was actually happening. The error popup was helpful, the message started with  VT-x/AMD-V hardware acceleration is not available on your system...

If you see a similar error you will need to enable Intel Virtualization Technology in your BIOS settings. A bit of googling should help you find out how to do that for your specific motherboard.

After enabling virtualization I tried vagrant up again...

Second Error: 
This might look familiar:

Error: Connection timeout. Retrying...

Wait, that's the same error again? I double checked my Homestead.yaml file and realized the path to my private key was wrong.

After correcting my SSH key path I tried vagrant up again...

Third Error: 
... found a tab character that violate intendation while scanning a plain scalar
at line ...

Despite the spelling error (indentation) this error message is fairly obvious. I opened Homestead.yaml in Notepad++ and turned on whitespace and tabs then converted the tabs into spaces.

Alright, now we're good to go! Let's try this again...  vagrant up ...

Oh... what? Another error! Are you kidding me???

Another Error:
.../HostsUpdater.rb 'initialize': Permission denied - C:/Windows.system32/drivers/etc/hosts (Errno::EACCES) ...

You will see this error message if you installed the HostsUpdater plugin and aren't running GitBash as administrator.

Close GitBash and 'run as administrator'...

Git Bash

$ cd ~/Homestead
$ vagrant up

After a minute or so I finally see the words: Machine booted and ready!
Let's SSH in to make sure it's set up properly. I prefer to use the Bitvise SSH console, so as a test I logged in and looked around:

Copy/paste the Host and Port values from the vagrant startup sequence in your console. Above I was verifying that my default Laravel installation was mapped properly.

Step 8: Test your site

If all goes well you should now be able to open a web browser and see your site. My first sites entry looks like this:


    - map:
      to: /home/vagrant/Code/Laravel/public

Let's see if this is working ... I type in the browser ...


So, was all of this worth it? I think so! Honestly, I doubt I'll get much use out of the Homestead box because it doesn't really mirror my actual server environment, but after dealing with the errors and configuration issues I've become much more confident using Vagrant and VirtualBox. Now I'm setting up my own custom Vagrant box which mirrors my live server environment ... I use virtual machines for mobile and game dev all the time and I'm so excited that I finally took the time to get this working for my web dev environments too.

I hope this helps some wandering Windows user out there. If it does, let me know. I would also like to give a HUGE thanks to Github User Terre Porter whose Laravel.IO thread helped me fill in a few missing pieces and introduced me to the awesome hostsupdater plugin for Vagrant.

Check out this thread on Laracasts for any errors or updates that haven't made it into this post yet:

I would also recommend getting familiar with Vagrant commands and don't be afraid to open up some of the Homestead scripts and Homestead source files to poke around and understand what's happening under the hood.

Next up, I'll be integrating this into my Grunt workflow...



  1. actually 'vagrant up' is wrong. this will require you to always 'cd' to homestead directory before issuing any vagrant command. but if you do 'homestead up' it will do this for you. also running all vagrant commands through 'homestead somthing' works too.

    also you don't really need bash. all this works through usuall windows command prompt quite well.

    1. Hi ConstB

      I did try the installation according to the laravel site and bash did not work for me in the command prompt (unknown command), i had to use git to enable bash to work.

  2. Thanks for the feedback @ConstB. I wouldn't say using 'vagrant up' is wrong, it's an alternate way that works (and afaik the only option that works if you install using Git instead of Composer ... if that's not true please share). I did explain why I preferred to use vagrant commands and I recommend you use the homestead commands if you're doing it the composer way.

    I updated Step 7 to clarify a bit more about the different installation options. You may also want to keep an eye on this Laracasts thread for faster updates: since I don't always have time to update my blog as often as I'd like.

  3. Hi

    I get this when trying to install the plugin:
    $ vagrant plugin install vagrant-hostupdater
    Installing the 'vagrant-hostupdater' plugin. This can take a few minutes...
    Bundler, the underlying system Vagrant uses to install plugins,
    reported an error. The error is shown below. These errors are usually
    caused by misconfigured plugin installations or transient network
    issues. The error from Bundler is:

    Could not find gem 'vagrant-hostupdater (>= 0) x86-mingw32' in the gems availab
    e on this machine.

    Also you say to "Export your public and private keys to your .ssh folder", where is that folder?


    1. The Windows .ssh folder is usually: C:\Users\{username}\.ssh

      As for the vagrant-hostupdater plugin, I didn't run into that issue, perhaps you might find a solution on their git repo:

    2. I run into the same error, its just a misspelled command... host-s-updater, therefore vagrant plugin install vagrant-hostsupdater

  4. Replies
    1. I do have this running on both Windows 7 & 8, you might need to change a few of the paths to their Windows 7 equivalent.

  5. Thank you so much for putting this guide together! It truly saved me hours of pain.

    I was using a WAMP type setup but decided to bite the bullet and move to Vagrant/Homestead - now that I have it working I'm so pleased that I took the time - all in all it took only a few hours to get everything running - and that is only as a result of this guide.

    I specifically did not want to install PHP / Composer on my fresh Win 7 platform so your Option 1 above is what saved the day as most other guides out there required PHP / Composer on the host OS (which seems kinda contra the idea of Homestead in the 1st place!)

    All I had to do in addition to the above was actually create the base laravel project once the VM was running in the mapped dir. I also had to run "vagrant destroy" and then "vagrant up" again be after editing the yaml file after the VM was provisioned.

    Once again thanks a mill!

  6. Make sure you use VirtualBox 4.2.30. Version 5.0 did not work for me.

  7. So... after all manuals I can't start this and did a question:

  8. This was a great post, helped me throughout the VM provisioning. Thank you!!!

  9. everything works fine....but when i run vagrant up...error: segmentation fault...

  10. Thank you for your post, I had problems adding homestead, then I uninstalled vagrant, and re-installed twice, now my windows 8 laptop simply says "vagrant: command not found" each time i try to check the vagrant version. Vagrant is still installed, and this path "C:\HashiCorp\Vagrant\bin;" is currently added to my User variables. Is there something else I'm missing? please help.

  11. I forgot to add that I currently have vitual box 5.0.6 and vagrant 1.7.2

  12. Be careful not to put (paste) tab characters in Homestead.yaml file
    I did that by accident when copying from this page, and got some funky Ruby errors. You can replace any accidentally pasted tab characters with notepad++
    I suggest you google on how this is done

  13. so the hostsupdater doesn't update my hosts file on windows. i don't get any errors but upon checking the hosts file, there are no entries in there. could the reason be, that i didn't use git bash but cmd to install and run (in admin mode of course)? when I add the hosts manually, I get a connection timeout ... but that's probably a different problem.

  14. Sorry but i feel there is some confusion between your posted step 4 and the laravel homestaed documentation.
    YOu say use option 1 - if you don't have php installed on your machine. (I removed wamp and so went with option 1)
    git clone laravel/homestead.git Homestead

    The laravel homestead documentation says:
    if you do not want to install php on your local machine to use:
    git clone laravel/homestead.git Homestead

    Can you clarify? Both are a little ambiguous. And just what should be the role of Composer also a little unclear.

    I did get the magic words' booted and ready', but couldn't get much going after that. The post was helpful, but might benefit from a little more elaboration.


  15. Missing piece of documentation?

    My setting up went fairly straightforward but when i got to to the step of looking at in the browser, I couldn't get it to work. Kept getting file or directory not found. Solution...

    I went back to source laravle documentation and noticed some additional commentary on 'Luanch the Vagrant Box'.

    Instructions on setting c:\windows\system32\drivers\etc\hosts
    set a line to

    Once i did this i was able to go into browser and get it to work. Also just for clarity's sake, when you said go into browser i kept thinking i had to do something within the vagrant environment - i didn't realize you were referring going back to my window machine bringing up a browser and then plugging in the address. I was trying to bring up a browser within vagrant - don't know if that can even be done.

    I am using a windows 10 pro setup. Still your post was helpful. both from a techincal point of view - samples to match to - and morale wise, to know that others struggled with this but with persistence it could be done. thanks much

  16. When I tried to add the the homestead vagrant box I kept getting the following error

    "Vagrant is attempting to interface with the UI in a way that requires
    a TTY. Most actions in Vagrant that require a TTY have configuration
    switches to disable this requirement. Please do that or run Vagrant
    with TTY."

    If you get this error, just put --provider virtualbox in the command. So your command should be:

    vagrant box add laravel/homestead --provider virtualbox

    Works like a charm!

  17. Here is a fix for anyone getting the following error like me when trying to add the vagrant box:

    "Vagrant is attempting to interface with the UI in a way that requires a TTY. Most actions in Vagrant that require a TTY have configuration switches to disable this requirement. Please do that or run Vagrant
    with TTY."

    All you need to do is add --provider virtualbox to the command. So the command should be:

    vagrant box add laravel/homestead --provider virtualbox

    It will install at this point.

  18. I'm on Windows 7, and when I run vagrant box add laravel/homestead I get this:

    $ vagrant box add laravel/homestead
    ==> box: Loading metadata for box 'laravel/homestead'
    box: URL:
    Vagrant is attempting to interface with the UI in a way that requires
    a TTY. Most actions in Vagrant that require a TTY have configuration
    switches to disable this requirement. Please do that or run Vagrant
    with TTY.

    The solution was to run

    $ vagrant box add laravel/homestead --provider virtualbox

  19. Tanks Sherri, this was a great help installing it on Windows 10. Only thing now to solve is the 'No input file specified.' I get. But I'll figure it out.

  20. What if I want to install in D drive
    I'm getting errors when installing in D drive

  21. Great tutorial, many thanks!! I had another catch to solve in the process. VT-x wouldn't run on my Windows 8.1 machine because I had Hyper-V running, and Windows 8.1 doesn't allow VT-x and Hyper-V enabled at the same time. Simple solution: In Windows Control Panel: "Uninstall program" > Turn Windows features on/off > Hyper-V: uncheck. Reboot. Success: VT-x working.

  22. Really Great tutorial, I Appreciate it