How To Run WordPress Locally With Vagrant


I’ve always been somewhat disappointed with the available options for running WordPress locally. There are pros and cons to each method (MAMP, WAMP, XAMPP, native, self-compiled, Fink, Homebrew, etc) … but they’ve taken too long to setup, don’t allow for enough configuration options (or in most cases allow me to run multiple WordPress websites at the same time) and leave unused config files and data deep inside my computer when I decide to uninstall. Vagrant is a new way of approaching this setup and seems to solve all of the issues I’ve had in the past when trying to get a local environment up for WordPress.

Vagrant makes it easy to run a full virtual linux (or Unix) server on your local machine … kind of like you’d run windows on a mac using VMWare (only with much less RAM & CPU being drained on your local machine).

Vagrant isn’t always used to run WordPress locally (obviously, it has many…many other uses) but I’ve found that one of the main ways I use Vagrant now is for running a LAMP (Linux, Apache, MySQL & PHP) server locally … which I then run WordPress on.

Why Vagrant?

There are several reasons why I think Vagrant is a great solution for running WordPress locally. Here are a few:

  1. Its relatively easy to get working
  2. You can create a LAMP server that will run the same whether its on Mac or Windows
  3. If you work in a team then you can make changes to your LAMP server specific to your team and each member can have identical local environments
  4. You’ll be running your site with Linux locally (most webhosts run on Linux) … so your local environment will be as close as to your production environment as possible
  5. Your website files will be located locally (for development / design purposes) and can be edited with your favorite editing software (TextMate, Notepad++, Sublime, Photoshop, Espresso, vi, emacs, etc) … when you’re done editing, and things look good locally you can ftp the files up to your web host.
  6. You can run several (possibly conflicting) environments side by side in different vagrant boxes on your local computer. I have a lamp box and a ruby box now … But I could configure boxes to run Java, ffmpeg or any other number of different environments that would be difficult to setup together in a clean way natively.
  7. Advanced users can ssh into these virtual machines, add new virtual hosts, install new software (via apt-get, yum, etc), run nginx instead of apache or pretty much anything else you want to do  … you can even create your own network of vagrant servers if you want
  8. Vagrant boxes are easy to remove from your computer without leaving unused files cluttering your system

Setting Up Vagrant

Here’s how you can set up Vagrant on Mac (the Windows setup should be almost identical) for running WordPress locally. The box that Vagrant maintains ( is a basic Ubuntu Linux virtual machine … so, I took that box, added the LAMP stack on top of it and have made it available for you to easily get this working on your computer:

  1. Download & Install Oracle’s VirtualBox application from
  2. Download & Install Vagrant from
  3. Download WordPress from
  4. Unzip wordpress anywhere on your local machine (double click the file you just downloaded)
  5. Open Terminal (its in Applications -> Utilities)
  6. Drag the wordpress folder you just unzipped from Finder into the Terminal icon in your dock (or just “cd” into your this directory if you’re comfortable with the command line)
  7. Now issue these three commands (don’t be alarmed if the first command takes a while — Vagrant is downloading a full virtual machine) …
  8. Go to http://localhost:8080 in your browser, you’ll magically see the setup for wordpress (if all went well). When setting up you can use the following database credentials:Database Name: vagrant
    Database Host: localhost
    Database User: root
    Database Password:vagrant

    I’ve also installed PhpMyAdmin with this box so if you need database access you can just go to http://localhost:8080/phpmyadmin and use the database username / password from above.

Getting to Know Vagrant

Here are some other useful commands that you can run in the terminal to interact with vagrant now that its installed:

To power up your vagrant box:
vagrant up

To access your box via ssh:
vagrant ssh

To suspend your vagrant box:
vagrant suspend

To shut down your vagrant box:
vagrant halt

To destroy your vagrant box (this will remove it from your wordpress directory):
vagrant destroy

To remove the vagrant box from vagrant itself:
vagrant box remove caseproof-lamp

The Vagrantfile

You may have noticed that when you ran vagrant init ... that it created a file in your wordpress folder named ‘Vagrantfile’ … this is the vagrant config file for your current vm. It has all kinds of useful options … but perhaps the most useful one is for forwarding ports which you can use to change the port your local website will be available on (so instead of http://localhost:8080 you could access it on http://localhost:4567) which is going to be necessary if you use this same box for multiple different websites on your local machine.

Vagrant everywhere

Now, of course, this vagrant box is a full LAMP server so now if you wanted to run Drupal, Joomla, or CakePHP you could easily download into another directory and since you don’t need to add the caseproof-lamp box twice — just issue vagrant init caseproof-lamp, edit your Vagrantfile to forward to a different port (remove the # before the forward port line and replace 8080 with whatever port you want), issue vagrant up and you’re done.

One thing to note is that if you need to do some more advanced things with your Apache or PHP configuration … you’ll have to ssh into your box and configure it just like you would a Linux server. So, if you have this requirement and you’re uncomfortable with editing files on your vagrant box then it may be best to go with MAMP PRO or something that will provide a GUI for this. However, if all you want is to get a standard WordPress site up locally then this box should work well for you.

I’ve also got a ruby box that is configured with Ruby, Rubygems, Apache, Passenger, Git & MySQL (yeah, you can install Postgresql or Mongodb if you need to). I find that with ruby I still like to ssh into vagrant (mainly because of all the commands you have to run within the ruby environment) … the shared folder with your vm is located in /vagrant/ once you’ve ssh’d in. I’ve also set this box to run on port 3000 rather than 8080.

If you want to do some more advanced stuff or need more detail than I’ve offered here, there’s quite a bit of documentation over on the Vagrant Website.

I’m still playing around with Vagrant though. If you’re doing something cool with Vagrant I’d love to hear about it here.


  1. Shawn Orcott says:

    I gave up tinkering around on WordPress locally because of all the issues you mentioned. You lit a fire under me to test it out with Vagrant though. It could provide some use in my work.

    Cool post! I’m loving Pretty Link too. I just got the pro version and it’s slick!

    • Blair Williams says:

      Thanks Shawn — yeah, you’ll have to let me know what you think once you try it out.

  2. Hey, Shawn,

    Is it possible to create multiple or tiered affiliate programs?
    We have one program for one-time referrals that convert and then, there is the recurring commission partner program for those who are actively engaged resellers, fully supporting their customers.

    Is settlement using automatic? Or, does it require manual management?

    We are interested in offering this to our customers. Do you have any recommendations on how to manage a program like that?

    And, lastly, I’d love to talk to you about Venntive. It goes far beyond AWeber! Is it difficult to create a WP plug-in?

    Please reach me directly via lksugarman at venntive dot com.

    • Blair Williams says:

      Yeah well Affiliate Royale supports multiple-level affiliate programs.

      We haven’t looked at creating support for venntive but it should be pretty straight forward to develop an add-on to Affiliate Royale that would give Affiliate Royale that integration.

  3. Blair,
    This is a totally new approach which has a lot of appeal. I’ve had good luck running a single WordPress install using Bitnami ( stacks, and also their stacks for Wikimedia and other open-source apps. Gets tricky – at least at my skill level – to install multiple instances of WordPress. I assume people use these for the same purpose I do – to sandbox themes and plugins. My brilliant partner Garry Osgood set up a VPN, and now we’ve got a duplicate version of each blog on a secure VPN. (We’re still trying to find a way to post on the secure blogs, and pipe the posts to the public, hosted versions). But as our readership has gone up, hacking has gone up, and we use the secure versions to overwrite any corruptions on the public hosted sites.
    Looking forward to trying out Vagrant; although the other possibility is to use a dedicated Linux box. Also looking forward to trying out your other products.

    • Blair Williams says:

      Awesome … yeah, you can install multiple wordpress instances using apache virtual hosts on the same vagrant box if you want … I think the BitNami VMs are really a fully pre-configured environment kind of like these boxes I setup for this post … so if you want to run multiple wp instances you’ve got to do some configuration with the Apache Virtual Hosts.

      Loading up a Vagrant box on your local machine gives you access to a real, dedicated linux environment. Whether I’m accessing a linux machine via vagrant on my local machine or out in the cloud via Amazon AWS or Linode, there really is no difference other than where the actual environment lives.

  4. What does vagrant buy me over just installing a lamp server in virtual box or vmware player? It looks like the only thing vagrant does is allow me to start/stop the server easily? Am I missing something?

    I do agree with some of your points that running in an emulated xammp/mammp/wamp environment can be different then running on a native linux box. I ran into a few problems with xammp which is why I started running a lamp server in virtual box.

    • cartpauj says:

      Danny, you’re right, there’s not much difference other than there are many pre-configured vagrant boxes available which you can use in the snap of a finger “well almost” to have a specific type of environment up and running. It’s very handy for people who want to get a test environment up quickly, but don’t necessarily have all the know-how to configure a LAMP environment via command line.

    • cartpauj, Thanks. I have just used VMware player for this. There are several pre-configured lamp servers for that also.

    • cartpauj says:

      Yes, I’m a fan of local WAMP/LAMP installs myself. Haven’t had any troubles running multiple instances of PHP/MySQL/Apache test sites at all.

      I know Blair does a lot of different types of projects, that require setups outside of the typical LAMP/WAMP package(s). That’s where multiple vagrant boxes can really be handy.

      Another benefit of Vagrant, if I’m understanding Blair’s post correctly, that I forgot to mention in my first reply to you, is that it makes it easy to modify your project files without having to actually SSH/FTP into the box to get to them.

  5. Awesome thanks for the Tut – got my first Vagrant box up and running and WordPress running smoothly. But I develop alot of different sites at once – could you give me some pointers on how to setup this same box, but for use w/ multiple WP installs, each w/ their own db?

    Is it as simple as setting up the Vagrant box in a directory and put the WP installs in Sub-directories – then using PHPmyAdmin to create new databases? Or are there paths that need changing etc?

    • cartpauj says:

      Hi Tanner, Vagrant is a Virtual Machine. It essentially sets up an Ubuntu Lucid server. You can read on using multiple hosts on the same machine here:

      Yes you will want to install PhpMyAdmin to manage multiple DB’s and users, or learn to manage MySQL from the command line.

    • cartpauj says:

      Reading Blair’s post a bit further, it appears his pre-configured Vagrant template has PhpMyAdmin installed and ready to use, as well as a root user/password for MySQL.

    • So yeah, you could either run a different vagrant boxes per wordpress website (just configure a different port for each) this is probably the easiest approach (this is what I do) but this could start draining resources on your local machine. So, another approach could be to just ssh into your vagrant box, add some additional folders & virtual hosts (as per @cartpauj’s comment above) then in your Vagrantfile you’d add additional shared folders. As for the addresses that you’d reach your new instances, you could just set each to go to a different port and then forward those ports in the Vagrantfile appropriately or you could use named hosts and then set these names in your local /etc/hosts file.

  6. Nice tutorial..but what if I want to edit the ini files and may be upgrade the php version? How can I do all that?

    • The good news about using vagrant is that your local environment is just as configurable as any web server… you just have to be somewhat comfortable with the command line to do some things (like this).

      You have to use the “vagrant ssh” command to ssh into the vagrant box. Then you can edit the php.ini file to your heart’s content with vim … use the following commands:

      sudo vim /etc/php5/apache2/php.ini

      or you can use nano if you’re not used to vim:

      sudo nano /etc/php5/apache2/php.ini

      and then after you’ve saved your php.ini you just reboot apache on your vagrant box:

      sudo service apache2 restart

  7. Teletubbi-OSX says:

    [default] VM already created. Booting if it’s not already running…
    [default] Clearing any previously set forwarded ports…
    Vagrant cannot forward the specified ports on this VM, since they
    would collide with another VirtualBox virtual machine’s forwarded
    ports! The forwarded port to 8080 is already in use on the host

    To fix this, modify your current projects Vagrantfile to use another
    port. Example, where ‘1234’ would be replaced by a unique host port:

    config.vm.forward_port 80, 1234

    I try to set Port on 3307 in Vagrantfile. But there is no effect.

  8. Hi there,
    I really like vagrant, ist definitive better than xamp or lamp.
    I have only one problem the LiveReload app does not work in vagrant.
    Do you know any way to do LiveReload with vagrant ?

  9. I gave you a shout-out on Twitter for this great tutorial!

    I do have a question, however. I have MAJOR caching issues. If I replace a graphic, for instance, it WILL NOT CHANGE, no matter how many times I refresh or hard-refresh the page. I was wondering if this might be in play:!topic/vagrant-up/7RgBxo6EksQ

    I’m not sure if the caseproof lamp box is something you made or not, or if this was taken into consideration. I gave myself a crash course in unix, ssh and vi, and was able to add “EnableSendfile off” to the bottom of the etc/apache2/apache2.conf file and restart the server, but it doesn’t seem to have fixed the issue.

    Does anyone have any ideas? Thanks!

  10. Ha! Ha! You guys just make things to complicated on your selfs. All you need to do is run Linex or windows server on a desktop with a PHP and MySQL server running. Why make it all so complicated?

    • Erm… because you might want different setups for different projects? Different versions of PHP, different database types, separate projects with their own file structure & server set-up that you want to be able to package for other people to use without having to follow a strict and lengthy list of instructions to make sure they have exactly the same environment?

      The whole point is that Vagrant makes what can be very complicated and painstaking a heck of a lot simpler, especially with a team of developers working on several complex projects, each with their own specific requirements.

      Thanks for enlightening us with your wealth of knowledge and experience though, Larry.

  11. Keep getting a error message if I type the following into a Terminal vagrant box add caseproof-lamp
    The program ‘vagrant’ is currently not installed. You can install it by typing:
    sudo apt-get install vagrant
    But vagrant thas been installed . If it makes any difference(hopefully not) this vagrant install is being done on Linux Mint 14. have done reinstalls, no luck. I am trying to get LAMP to work on a Linux OS.

  12. Haneef Mubarak says:

    Do you have a 64-bit image (preferably ubuntu precise)? Alternatively, do you have a script to modify an ubuntu image to make a LAMP image?


  13. I’d like to know how to connect to the DB inside the VM from my host HeidiSQL. As useful as PHPMyAdmin is, it’s not as useful as a standalone client for managing your DB.

    Any ideas anyone?


  14. After install apache, php and mysql, i cannot access to my vagrant box using “vagrant ssh” (if i reload my box after that) anyone knows something about this issue?