Skip to Content

A Drupal Developer’s Setup on Windows

UPDATE: 3/23/2013: In general, these instructions still work for Windows 8. While some of the UI aspects have changed, the basic directions are the same. One exception is when downloading PuTTy. Since it’s an unsigned .exe file, Windows will boldly claim that “Windows protected your PC.” Click More info followed by Run anyways and you’re on your way.

UPDATE: 4/22/2012: A few more scattered updates, plus a new section on setting up XDebug on Aptana for super-easy  debugger config.

UPDATE: 12/1/2011: Got a new work laptop so I’ve updated these instructions – mostly with regards to Drush (5.x branch has great Windows support) and some optional performance tweaks when setting up MySQL.

This page outlines what I’ve done to get a good Drupal dev environment – Apache, MySQL, PHP, Git, Drush and most Linux-style shell commands – running on Windows. There are other solutions out there and I’m always interested in hearing what others have done to optimize their setup. Please leave any suggestions is the comments.

This page DOES NOT go into migrating content from dev/staging servers to live servers. If that’s what you’re lo0king for, sorry. I’ve been to endless DrupalCon BoF’s, Drupal group meetings and numerous online conversations around content migration and there is no real solution except “wait for 8.”

I was lucky (???) enough to have my laptop’s motherboard fail so I was able to refine these steps on a brand-new computer with a clean install of Windows 7. It’s a pretty long process, but you only have to do it once…  Well, once per laptop failure.

Setting up a Drupal Dev Environment

  1. Install and configure WAMP Server:
    1. Install WAMP Server using the default settings. Be sure to pick the 64-bit version if you’re running a 64-bit Windows.  If you’ve got more than 4 GB of memory (which you should!) you need to run 64-bit Windows to take advantage of it. If you have a firewall running, you may get an alert about Apache HTTP Server communicating on various networks. If you’re only doing local development (meaning other computers will not need to access your localhost) then you can deny the firewall request.
    2. Start –> Control Panel –> System and Security –> Administrative Tools –> Services
      1. Double click the wampapache service. Set the Startup type to Automatic (Delayed Start), click the Start button, then OK.
      2. Repeat for the wampmysqld service.
      3. The delayed start option simple puts these services at the end of the list of services started when you computer boots up. If you really need to have your WAMP server running as soon as your computer starts, set the Startup type to Automatic.
    3. To start the WAMP Manager – which gives you easy access to the various WAMP services – automatically on start up, follow these steps. Otherwise you can run it off the Start menu as needed.
      1. Control Panel –> System and Security –> Administrative Tools –> Task Scheduler
        1. Click Create task… in the right-hand pane.
        2. General tab: name this task, tick the Run with highest privileges checkbox , ensure that Run only when user is logged on is selected, and that Configure for is set to Windows 7.
        3. Trigger tab: Click New… and set Begin the task to At log on, then click OK.
        4. Actions tab: Click New… and point Program/script to your wampmanager.exe (usually C:\wamp\wampmanager.exe) then click OK.
        5. Conditions tab: (if you’re on a laptop) uncheck Stop if computer switches to battery power, Start the task only if the computer is on AC power and every option in the Idle section. (Oddly, you need to check a parent item in order to uncheck a child item in this dialog…)
        6. Settings tab: uncheck Stop the task if it runs longer than and If the task does not end when requested, force it to stop.
        7. Click OK to create the task and reboot your computer to test it out.
      2. You can force Windows to show the WAMP Manager icon all the time by clicking the little up arrow next to the notifications area, clicking Customize…, and setting Aestan Tray Menu to Show icon and notifications.
      3. If you want to use Clean URLs, click on the WAMP Manager icon and select Apache –> Apache Modules –> rewrite_module.
      4. Click on the WAMP Manager icon in the task bar and select Put online .
    4. Decide where your localhost root directory will be. I recommend making this your dev root directory as well, such as C:\dev or C:\Users\<user-name>\Documents\dev. I use the latter option so I can keep all my important files in the same directory. In the following steps, we’ll call this <path_to_root>.
    5. Configure your httpd.conf file: click the WAMP Manager icon in the Taskbar notifications area and select Apache –> httpd.conf. If the system asks, set notepad.exe as the editor for this file type.
      1. Search for the line Include conf/extra/httpd-vhosts.conf and uncomment it (remove the leading ‘#’ character) and save.
      2. Search for DocumentRoot and change the directory to your <path_to_root> directory. The line should look similar to DocumentRoot "C:/Users/mikeker/Documents/dev". If you have spaces in your path name, the quotes are required.
      3. A couple lines below the DocumentRoot location you’ll find:
        # This should be changed to whatever you set DocumentRoot to.
        #
        <directory "c:/wamp/www">
        Do what  the man behind the curtain says and change c:/wamp/www to your <path_to_root>.
    6. If you have plenty of memory in your dev machine (and you should), give MySQL more room to work: in <path to wamp>\bin\mysql\mysql<version-number> rename the existing my.ini to my-original.ini, then rename my-innodb-heavy-4G.ini to my.ini.
    7. Drupal loads a lot of files and WAMP’s default realpath_cache_size is easily overwhelmed. Click the WAMP Manager icon and select PHP –> php.ini, uncomment (remove the leading semi-colon) the realpath_cache_size = 16K line and bump the number up to 16M or 32M. Save and close php.ini.
    8. Setup some convenient shortcuts: I usually put these on my desktop but they can go anywhere that makes sense for you.
      1. The system’s hosts file, which allows you to point certain Web addresses to your WAMP server instead of the Internet: Set the shortcut location to: notepad.exe "<path to hosts file>"  (You need to include the quotes if there are spaces in the path). The hosts file is usually located at C:\Windows\System32\drivers\etc\hosts.
      2. WAMP Server’s virtual hosts config file: notepad.exe "<path to wamp>\bin\apache\<apache-version-number>\conf\extra\httpd-vhosts.conf"  (Again, you need to include the quotes if you have spaces in the path). The virtual hosts config file is usually located at C:\wamp\bin\apache\Apache2.2.17\conf\extra\httpd-vhosts.conf, though the Apache version number can change with new builds of WAMP Server.
      3. Right-click on each shortcut and select Properties. On the Shortcut tab, click Advanced… and check the Run as administrator checkbox.
      4. Double-click on the virtual hosts shortcut, click Yes to the UAC warning, and either delete or comment out the examples that come with the file.
    9. Click the WAMP Manager icon and select Stop All Services. Navigate to <path to wamp>\bin\mysql\<mysql-version-number>\data and delete (or rename) ib_logfile0 and ib_logfile1. Click the WAMP Manager icon again and select Start All Services.  If the icon doesn’t return to its green, “all is ok” state pretty quickly you’ve likely got an error in your httpd.conf file or your httpd-vhosts.conf file. Look at the Apache error log (WAMP Manager: Apache –> Apache error log) for clues.
    10. If you have real-time malware detection software you may want to create an exemption for the MySQL data directory (eg: C:\wamp\bin\mysql\mysql5.5.16\data) since files in there will be changing all the time, causing your malware software to run overtime.
  2. Install PuTTY using the default options (I recommend using the Windows installer option):
    1. PuTTY allows you remote access to servers via SSH, as secure way to issue commands on your site’s server from your dev machine. If you do a lot of work on remote server, consider pinning the PuTTY program to the Taskbar.
    2. PuTTY also comes with PuTTYgen which lets you easily create and manage SSH key, which is what Git uses to authenticate a user on a given server. We use it in a bit.
  3. Install and configure Git:
    1. Install Git for Windows (follow the Download for Windows link) changing only one of the default settings: On the Configure line endings dialog select Checkout as-is, commit as-is. Unless you’re using a non-*nix aware code editor (possibly Visual Studio?) your it should be able to handle either type of line ending. If you’re unsure, go with the default as this is an option that is easy to change later, or even on a project-by-project basis.
    2. Click the Start menu and type git. Click on the Git Bash option then right-click on the Git Bash icon in the Taskbar.
    3. Click Pin this program to the taskbar
    4. Right-click (again) on the Git Bash icon in the Taskbar, right click on the Git Bash item and click on Properties

      1. Shortcut tab: Set the Start in option to your dev root directory, in my case: %HOMEPATH%\Documents\dev
      2. Options tab: set Buffer Size to 900 (or however large you want your scrollbar to go back), ensure Quick Edit is checked.
      3. Layout tab: Set your preferred window size in the Window size and Window position fields, making note of the window width setting – you’ll use that later on.
      4. OK the Properties dialog.
    5. Go to your drupal.org user account page, click Edit followed by Git access.

    6. Copy the Git user configuration lines and paste into your command shell.  This tells Git how to identify you to drupal.org and other Git servers. If you haven’t already, check the I agree to these terms checkbox in the Git access agreement section.

    7. I recommend the settings outlined on Drupal.org for configuring Git. The most important one is setting core.autocrlf and core.safecrlf to false -- that prevents a lot of bogus end-of-line warnings if you use Coder to check your coding standards. Instructions to setup Coder to work with Drush is a little farther down.

    8. If you haven’t already uploaded an SSH key to drupal.org, switch to the SSH Keys tab and click the Add a public key link.

      1. From the Windows Start menu, type puttygen and select the PuTTygen option that appears. This utility makes it easy to create and manage SSH keys.
      2. Click the Generate button and wiggle your mouse over the blank area as requested to provide some random input.  When the key is generated, add a passphrase to the key and click Save public key then Save private key.  Keep in mind that your public key is only as secure as your private key/passphrase, so use a reasonably complex passphrase and don't put your private key anywhere accessible to the general public.
      3. Copy the text generated in the large text box at the top of PuTTygen and paste it into the Key field on drupal.org and click Save.
  4. Grab a few binaries that Git doesn’t install
    1. The Git shell install does not include the wget command and uses a piss-poor version of tar, both of which Drush uses extensively. We’ll grab better versions from GnuWin32, an open source collection of Linux shell commands for Windows. Download the wget and libarchive packages, grab the Complete package, except sources executable and run the installer using the default settings (feel free to uncheck the options to create Start menu folders, etc.)
    2. Navigate to the folder where GnuWin32 installed the binaries, usually similar to C:\Program Files (x86)\GnuWin32\bin, and rename bsdtar.exe to tar.exe.
    3. Add the bin directory to your path. While we're in here, we'll add a few other paths as well. In your Git shell type vim ~/.bashrc and add the following code and save:
      # GnuWin32 tools
      # Remove the " (x86)" if you're running 32-bit Windows
      PATH="/C/Program Files (x86)/GnuWin32/bin":$PATH
      
      # Support PHP from the command line
      # Update "php5.3.13" to point to the version of PHP installed
      PATH=/C/wamp/bin/php/php5.3.13:$PATH
      
      # MySQL for the commandline, in particular mysqldump
      # Update "mysql5.5.24" to point to the version of MySQL installed
      PATH="/C/wamp/bin/mysql/mysql5.5.24/bin":$PATH
      
      # Point Git to the correct SSH client
      export GIT_SSH="/C/Program Files (x86)/PuTTy/plink.exe"
      
      # This should come after any PATH additions
      export PATH
      
      If you are unfamiliar with vim, check Google for some quick tutorials or use your favorite text editor. Note: if you have spaces in your path names, you need to enclose the entire path in double-quotes. The colon (:) character separates one entry from the next. The tilde character (~) can be used as a shortcut to $HOME, which on Windows is usually at c:\Users\<user-name>. Also note that we have to add the GnuWin32 binaries before the rest of the $PATH variables so that bsdtar, now renamed simply tar, will be found ahead of Git’s tar executable.
    4. There are plenty of other *nix commands not included with the Git shell (eg: more). If you grab GnuWin32 installers for those commands, they should use the same bin directory.
    5. Close and reopen your Git shell. Type
      wget --version
      and check that you don't get any error messages.
  5. Install and configure Drush – this part got a lot easier after the 12/1/2011 update of this page. (Note: there is a Windows installer for Drush, but I like having more control over where and what is installed. But if you’re not having fun playing around on the command line, it’s a completely acceptable option. Just be sure to unselect the PHP runtime option and skip steps 1 – 4, below).
    1. Go to the Drush project page, right-click on the tar.gz download option for the latest release of the 5.x branch, and select Copy link address (or whatever option your browser shows for copying a link address). The 5.x branch includes much better support for Windows than previous version of Drush. Kudos to the Drush developers for not treating Windows users as second class citizens!
    2. In your Git shell: Change directory to wherever you want to install Drush, (e.g.: cd ~/Documents; mkdir bin; cd bin).  Type wget <url_of_drush_5.x_download> followed by tar –zxvf <drush-5.x>.tar.gz.

      Note: you can right-click on the Git shell to paste, or the keyboard combination of alt+space e p will select Edit –> Paste from the system menu. You can also hit the tab button to autocomplete filenames, meaning you probably only need to type tar –zxvf drush and hit tab to unpack the download.
    3. In your Git shell type vim ~/.bashrc and add the following code between the GnuWin32 bit and the export $PATH line and save:
      # Drush
      export DRUSH_PHP=/C/wamp/bin/php/php5.3.8/php.exe
      #                 ^-- Replace with your path to php.exe
      export COLUMNS=110
      #              ^-- Replace with the window width noted above
      PATH=~/Documents/bin/drush:$PATH
      #    ^-- Replace with your path to Drush
    4. While you’re in the .bashrc file add any alias or other shortcuts you like to have (e.g.: alias ll=’ls -l’)
    5. Exit and restart the shell. Type drush status to see if everything is working correctly:
      mikeker@MIKEKER-LAPTOP ~/Documents/dev
      $ drush status
       PHP configuration     :  C:\wamp\bin\php\php5.3.8\php.ini
       Drush version         :  5.0-dev
       Drush configuration   :
       Drush alias files     :
  6. Optional: Install PEAR and DrupalCS to ensure your code adhears to the Drupal Coding Standard.
    1. Install PEAR
      1. Download the go-pear.phar script and save it to <path_to_wamp>/bin/php/php<version_number>/go-pear.phar.
      2. Open a command shell as administrator (Start -> type cmd -> right-click on the cmd.exe option and select Run as administrator), navigate to where you saved go-pear.phar and type php -d phar.require_hash=0 go-pear.phar followed by Enter.
      3. The script should show you a list of file locations. Hit Enter to accept the defaults and continue.
      4. PEAR will install and may warn you about the PEAR directory not being in the PATH -- that's fine.
      5. When prompted, select Y when asked to alter php.ini. Don't close the command prompt, we'll need it in a bit.
      6. Open Windows Explorer and navigate to your PHP directory. You should find a PEAR_ENV.reg file here. Double-click it to add the PEAR environment variables to your registry.
      7. At this point you can run PEAR in command prompts (but NOT the Git shell -- .bat files don't play well with the MSysGit shell). Since I don't install PEAR packages more than once every blue moon, that works fine with me. If you do fiddle with PEAR packages regularly, you'll want to include the path to your PHP directory in your Windows path environment variable (as opposed to adding it to your .bashrc as we did earlier).
    2. Install Code Sniffer and configure it to work with Drush
      1. Back in the command prompt (not a Git shell), navigate to your PHP directory (eg: c:\wamp\bin\php\php<version_number>).
      2. Type pear update-channels and hit Enter to ensure you've got the latest and greatest.
      3. Type pear install PHP_CodeSniffer and hit Enter.
      4. The following commands will install Coder as a Drush extension, open a Git shell for these. This works fine UNLESS you have coder installed as a module in a project you're working on. My preferred config is to do my code checks with Drush, but if your situation doesn't allow it you can install coder anywhere else that Drush will pick it up on a project-by-project basis. See the Drush README Commands section for details.
        cd ~
        # Check if .drush exists, if not
        # mkdir .drush
        cd .drush
        drush dl coder
      5. Back in the command prompt with administrative permissions, navigate to your PHP directory (eg: c:\wamp\bin\php\php<version_number>) followed by \pear\PHP\CodeSniffer\Standards. From here type mklink /j Drupal %HOMEPATH%\.drush\coder\coder_sniffer\Drupal and hit Enter. If you placed coder someone other than your ~/.drush folder, you'll need to replace the second argument with the appropriate path.
      6. Test it out by opening a Git shell (we should be done with command prompts for now...), navigating to a Drupal install and typing drush dcs index.php. Note: if you're working in a Git repository, you'll get errors regarding invalid end-of-line characters and files not ending with a single newline. That's because Git converts Unix line endings to Windows when you checkout files.
  7. Install and configure your favorite code editor, in my case Aptana’s version of Eclipse Sublime Text 2. (Note Eclipse/Aptana config instructions have been moved). My ST2 configuration is a work-in-progress.

You’re ready to rock! Go forth and build amazing Web sites.

Basic workflow for a new project

When I’m starting work on a new site, here’s my basic workflow:

  1. If needed, click the WAMP Manager icon, select phpMyAdmin, create a database and user for this project and give the user the needed permission for the new database.
  2. Edit the hosts file: Double-click the hosts shortcut created above, click Yes to the UAC warning, and add a line similar to 127.0.0.1  local.example.com to the file and save. I like to preface all localhost addresses with the local subdomain so that it’s easy for me to tell what is live and what is dev. Plus local.example.com will still work with multi-site configurations of Drupal and it’s easy to switch from a given page on the live server to the same page on the dev server (assuming you’ve copied the database recently) by just swapping www for local.
  3. Edit httpd-vhosts.conf: Double-click the shortcut created above, click Yes to the UAC warning, and add code similar to:
    <VirtualHost *:80>
        DocumentRoot "<path_to_root>/example.com/drupal-7.0"
        ServerName local.example.com
    </VirtualHost>
    (or whatever the current version of Drupal is) and save the file. (And make sure the example code is removed or commented out as mentioned above).
  4. Restart Apache: click the LAMP Manager icon then Apache –> Services –> Restart Service.
  5. Open the Git shell and navigate to <path_to_root>/example.com  and type drush dl.
  6. Point your browser to local.example.com and the Drupal install screen should come up

selection

thank for information... very cool..

Great stuff! Just what I've

Great stuff! Just what I've looking for so long on setting up a Drupal Dev Environment. Thanks.

One word - Quickstart

Drupal Quickstart - http://www.drupal.org/project/quickstart

Sure, but...

Sure, you can use Quickstart, but if you don't like the defaults you're still "hacking up" the system. Also, this setup works better for systems with >= 4GB of RAM since each element (PHP, Apache, MySQL, etc.) runs as it's own process rather than reserving half your memory for a virtual machine that may not need all that memory most of the time or runs out of memory before your computer is really out of memory.

The argument that a virtual machine running a LAMP stack better matches what you'll find running on your servers is bogus. A VM is still a port of code from one platform to another -- just like WAMP or XAMP.

But to each their own. I'm happy that the Quickstart project helps get people up and running with a proper dev environment easily and quickly. It's just not my preferred option.

This is simply amazing i like

This is simply amazing i like the way you thoroughly wrote about this step by step.

git usage

This is really an amazing stuff. I am a professional PHP developer but have never used any CMS. Now i am planning to start learning Drupal. I am not a user of git version control system. My question is, is it really necessary to install git and use it along with drupal? Please suggest me the alternates if available.

Git is not needed, but...

Thanks for the coments. No, Git is not necessary. But if you're a developer, as you get more involved with Drupal you'll find youself wanting to use it. Git is what drupal.org uses for version control. If you wanted to test a patch from a project's issue queue or (better yet!) submit a patch for a big you found, you'll need to have Git installed.

Regardless if you're collaborating, it's useful to use Git (or any other version control system) on your local work to give you the ability to undo large chunks of changes to your code. With Drupal, just remember that your code and your database are closely intertwined. So if you're setting a snapshot that you want to revert to, be sure to snapshot the database as well as your code.

As to alternatives, there are centralized version control systems such as CVS or SVN as well as other distributed systems like Mercurial and Bazaar. I've worked with CVS and SVN before and Git is a much easier system for multiple developers to work with. I don't have any experience with Mercurial or Bazaar.

Unlike when working with CVS or SVN, I find myself making many, small commits when using Git which makes it easier to later remove a given change or track down a regression later on.

Hope that helps.

git

Thanks very much for this - clear and useable for many projects and the basic workflow has explained a lot too Wasn't sure exactly where the .gitconfig and .bashrc files should be & where they should be run from - get 'sh.exe": wget: command not found'?

Can't find .bashrc either

I'm on Windows 8 with Drupal Dev Desktop (with Drush installed) and went through your steps, but i'm stuck not being able to edit with vim to set path in .bashrc. I've tried to find the file to edit it manually and it's not anywhere. Yes, i'm able to view 'hidden' files, but nothing. I've also found that sometimes it's stored in a file called .bash_profile, but I cannot find that either. Do I need to create this? If so, where do I put it? I'm obviously new to Linux and command line stuff, but learning. Thanks!

Location, location, location...

You want to put .bashrc in your %HOME% directory, usually at c:\users\<your_user_name>\.bashrc. If you're using the Git shell, you can type cd ~ (that's a tilde) to jump straight to your home directory. If .bashrc doesn't exist there already, go ahead and create it -- make sure to include the leading dot . To see the changes you need to close your shell and reopen it as the .bashrc file only runs when then shell is first instantiated.

Ditto with the .gitconfig file, though there are a lot of other locations you can put that file depending on how narrow or universal you want your config chnages to be.

Good luck!

Thank you for this great

Thank you for this great stuff! I am a professional PHP developer but have never used any CMS. Now i am planning to start learning Drupal. Hope the information from this site will help me in my beginnings.

Worth Its' Weight Gold

Thanks much. This is the most useful post on setting up Drupal on Windows I've seen (in my 6 years working with Drupal). That said: I suppose all us Windows people should be using Virtualbox, Vagrant, Puppet yadda-yadda. Definitely the best way to go these days -- but I still find myself using WAMP much of the time. Thanks again! Adrian

Virtualboxes and yadda yadda...

Hi Adrian,

Thank you!  I'm glad you found it useful.

Regarding Vagrant, VB, Puppet and their ilk: you will always, always, always get better performance out of a decently turned machine running a native version of Apache/MySQL/PHP than you will out of a Virtualbox doing the same. Granted, it's easier to get to that decently (or even highly) tuned stack using a Vagrantfile with all the right settings. And if you're contantly jumping between configurations (for example, if D8 makes the jump to PHP >= 5.4) then a VirtualBox setup is very nice to have.

I've been working on getting my Vagrant-based workflow dialed in. Once I do, I'll post that here. At this point though, it's only used for testing, odd-ball clients configs  and that once-in-a-thousand issue where it's related to something specific to the server config that can't be replicated on WAMP.

Post new comment

The content of this field is kept private and will not be shown publicly.