Setting up Rails on Windows Vista

This guide walks you through setup instructions for preparing a Windows Vista development machine to be used for general Ruby on Rails coding. This baseline setup is what we use for our LearningRails online course.

You will end up with a development machine with the following baseline components:

  1. Ruby and all basic Ruby utilities
  2. Ruby Gems package manager
  3. Subversion client
  4. MySQL database client utilities and server
  5. Gems for Ruby on Rails, Capistrano, Mongrel, Mongrel Cluster, and MySQL
  6. SSH Terminal Program
  7. Git client (UPDATED)
  8. Programmer’s editor or IDE

Note: In the command sequences we illustrate here, command line prompts are shown as C:\>.


This guide assumes you have a Windows computer running the current Windows Vista operating system with up-to-date service patches applied (SP1 or higher). It also assumes you have not set up alternate Ruby on Rails tools prior to running through this guide. If you have, then small adjustments may be required as you walk through the following instructions.

You will need to have access to an Internet connection to complete various download steps.

You will need to have administrator access to your computer to complete this guide. Some of the Windows installers may ask you for your password. With most of the installer programs described below, Windows Vista will present the famous User Account Control (UAC) dialog asking whether an unidentified program should be permitted to have access to your computer.

You should select the “Allow” option which will let the specific installer program continue. In the specific case of MySQL, the MySQL installation process is not compatible with UAC. We will walk you through temporarily turning UAC off so you can install MySQL.

The Recipe

Follow this recipe in sequence. If you have previously installed a particular component, you can usually skip the associated step.

Ruby and Ruby Utilities (irb, ri, rdoc)

The One-Click Ruby Installer does a lot of work for you by installing Ruby, Ruby Gems Package Manager, Rake, all of the other standard Ruby tools, and even the open source SciTE programmer’s editor. Additionally, the installer configures the command line interface path information, so the Ruby tools are ready to use in the Command Prompt program.

Download the latest installer (1.8.6 r26 as of this writing) and double click on it to get started.

Select all of the default settings and let the installer complete its work. Once done, open a Command Prompt (aka DOS Command Line) window by selecting the Start menu, then enter cmd into the Start Search text box and pressing return.

You can check that Ruby is installed by typing the command:

  C:\> ruby -v
  ruby 1.8.6 (2007-09-24 patchlevel 111) [i386-mswin32]

You should seem similar responses. If you get an unrecognized command error, try closing your Command Prompt window and opening another one.

Ruby Gems Package Manager

You next need to install the latest version of gem.

Check the version that gets installed:

  C:\> gem -v

You need 1.0.1 or newer. If you have an older version, you can update with the command line: gem update --system.

Installing a Subversion client

Subversion will be used to access your source code repository during development and deployments. You will need a current version of the Subversion command line client and you can use the official Windows installers on

Download the latest “Windows installer with the basic win32 binaries” option on the site. Double click the setup program and select the default options.

Once the installer is done, open a new Command Prompt window and check the installation:

  C:\> svn --version
  svn, version 1.4.6 (r28521)
     compiled Dec 20 2007, 16:33:06

Installing MySQL via the Offical MySQL Installer

You will be installing MySQL via the official Windows Essentials installer from This installer handles all of the setup steps for you.

NOTE: As of this writing, MySQL 5.0.51a and 5.1.23rc have bugs that prevent simple installation onto Vista. A workaround recipe is available but it is complicated. We recommend using a slightly older version, MySQL 5.0.45, as it doesn’t have the current installation bugs. We’ll update these instructions once fixes to the current MySQL line are available.

Unfortunately, the MySQL installer and Windows Vista User Account Control (UAC) conflict with one-another. You will have to temporarily turn UAC off.

First, go to the Start Menu, select Control Panel, and then click on User Accounts and Family Safety:

Click on the User Accounts link to open your account’s setting dialog:

Click on the Turn User Account Control on or off link. Assuming that User Account Control is still on, Windows Vista will ask for permission to continue with turning User Account Control off. Nice and circular, yes? Now you can actually turn UAC off. Unselect the checkbox and press OK.

You will be prompted to restart your computer. Go ahead and do so now.

One other change you will need to make is to open your Windows Vista Firewall to permit MySQL connections to the MySQL server port (3306). To do so, open Control Panel again, and select the Allow a program through Windows Firewall option of the Security group.

Press the Add port... button, and enter MySQL in the “Name:” field and 3306 in the “Port number:” field. Leave the protocol as “TCP”.

Press OK on the Windows Firewall Settings dialog box and close the Control Panel.

Finally, you can get on with installing MySQL. Double-click the community edition (open source) Windows Essentials MySQL setup program to get started:

Select the default (“Typical”) settings and location and let the program install itself. After it completes, a few ads will be shown, then a final dialog allowing you to configure the MySQL server. Make sure the check-box is selected and press “Finish”.

The “MySQL Server Instance Configuration Wizard” will run next. Choose the “Detailed Configuration” option and select all of the default choices. Doing so will configure the database to be running with settings best designed for a developer’s computer. When you get to the dialog offering the “Include Bin Directory in Windows PATH” option, we suggest you select it. If you don’t choose this option, you will need to manually set up your path so the “Command Prompt” program has easy access to MySQL client programs.

You will also be presented with a dialog to set a root password. If you are going to be working locally and aren’t worried about security, you can deselect “Modify Security Settings” and have a blank root password. We strongly suggest you set a password to be safe.

You can confirm that MySQL is running by trying to fire it up in the Command Prompt program:

  C:\> mysql -p -u root
  Enter password: ****
  Welcome to the MySQL monitor.  Commands end with ; or \g.
  Your MySQL connection id is 1
  Server version: 5.0.45-community-nt MySQL Community Edition (GPL)

  Type 'help;' or '\h' for help. Type '\c' to clear the buffer.

  mysql> exit

When you reboot your computer, MySQL will start automatically in the future.

Once you have confirmed MySQL is working, you can also reverse the steps above for re-enabling User Account Control.


While the One-Click Ruby installer added some common Windows oriented gems for you, you still need the Ruby on Rails gems and the gems used in the LearningRails course. Install them with the command:

  C:\> gem install rails capistrano mongrel mongrel_cluster

All installed gems (including Ruby on Rails and its dependencies, Capistrano, Mongrel, and Mongrel_Cluster) will get installed at their latest versions.

The MySQL adapter gem needs to be installed next.

  C:\> gem install mysql

Once the command completes, you should be all set with the baseline gems you will need for the LearningRails courses.

SSH Terminal Program

In deployment environments where your production or other remote servers are running a Unix-derived operating system, you will want to log in to those machines using the SSH protocol. A good Windows SSH terminal program is PuTTY. Download the complete Windows installer and double click to let it run.

You can select all of the default options. Once the installer finishes, you are good to login to your remote machines.

Installing a Git client

Git is all the rage in the Rails world now and has pretty much replaced Subversion as the version control system of choice. That said, both are in common use. The Git on MSys project team has done a nice job of building the git tools and a simple installer for Windows.

Download the latest installer (latest as of the last update of this article was Git- and double click the executable.

During setup, you will be presented with a number of screens. Select the defaults until you get to the following two dialogs:

  1. “Adjust your PATH environment” dialog. Select the “Run Git from the Windows Command Prompt”.
  2. “Choosing the SSH executable” dialog. Select “Use PLink” since we just installed Putty.

The installer should complete, and you can optionally review the ReleaseNotes.rtf file.

The installer command places the core git tools and the man page documentation (type git help _commandname_ for help) on your machine and updates the PATH so you can use git from the Command Prompt. ruby script\plugin install should find git and use it for installation of newer plugins.

Note that if you have an older Rails project, you’ll want to update to Rails 2.1 or newer to get the latest support for git. When you upgrade, update your project with the rake rails:update command.

Code Editing Tools

While you can get by with using a plain text editor like Notepad you will have much high productivity if you use a programming editor that is highly tuned to Ruby on Rails development. The One-Click Ruby installer automatically installed the SciTE programmer’s editor. SciTE is ok for basic tasks with one or two files, but we recommend trying some of the other programs below.

We use the commercial TextMate programmer’s editor for much of our day to day work on the Macintosh. TextMate is highly extensible through a collection of community supplied “bundles”. There is a Windows “look-a-like/port” called the E Text Editor that looks promising and includes much of the functionality found on the Mac. Even better, it is supposed to be compatible with TextMate bundles, so as functionality improves for one platform, it should become available on the other. Worth trying the trial at the least.

There are a variety of good open source or free programmer editors available too. On the open source side you can find ports of vim and emacs, both of which have add-ons to create a full featured Ruby and Rails development tool set. jEdit is a very extensible open source editor written in Java that has a decent Ruby programming plugin set.

Whatever editor you choose, be certain that it provides easy navigation among a large number of open files. Working with Rails applications generally involves dealing with a lot of small files, and that process needs to be efficient.

If you prefer an all-in-one tool, you should look at one of several integrated development environments that exist for Ruby. We use Netbeans in our LearningRails courses, but you should check out the numerous other options listed at

Add Your Comments

(not published)

Git 1.8.3

From: Ronald, 09/08/13 02:33 AM

Just to let you know that Git 1.8.3 no longer offers the option at installation to “Choosing the SSH executable” dialog. Select “ Use PLink” since we just installed Putty. - i have no idea how to do this through the command line.


From: Lee Kwon, 01/25/10 08:26 PM

You probably have a previous version of mysql installed. You need to delete the mysql service from the registry. There is a way to delete the MySQL service. For some reason, the newer versions of MySQL don’t delete the service after installation. All you have to do is manually go into the registry and delete the key. Reboot may be necessary. To access the registry, click the Start button, then in the search query where it asks you, “Start Search”, type in “regedit”. Open the registry editor and goto this folder: HKEY_LOCAL_MACHINE/SYSTEM/CurrentControlSet/Services All your services are listed in there. Just delete the service corresponding with MySQL.


From: Lee Kwon, 01/25/10 08:26 PM

You probably have a previous version of mysql installed. You need to delete the mysql service from the registry. There is a way to delete the MySQL service. For some reason, the newer versions of MySQL don’t delete the service after installation. All you have to do is manually go into the registry and delete the key. Reboot may be necessary. To access the registry, click the Start button, then in the search query where it asks you, “Start Search”, type in “regedit”. Open the registry editor and goto this folder: HKEY_LOCAL_MACHINE/SYSTEM/CurrentControlSet/Services All your services are listed in there. Just delete the service corresponding with MySQL.

problem during installation

From: mithila, 10/19/09 04:29 PM

I was just installing mysql onto my system and I got a problem in MySQL server Instance Configuration Wizard..where I am not getting any options to select that is to include bin directory option and windows as service.So ,please tell me how to do that and when I run in command prompt it is telling that bad file and not installed correctly...Please help me how to recover from that.

during instalation ror i meet this issue in my dev.log

From: neagaoleg, 08/08/09 04:26 AM

Status: 500 Internal Server Error no such file to load -- sqlite3

mysql gem installation

From: neagaoleg, 08/07/09 02:59 PM

it gives me an error while installing rdoc documentation for mysql

ROR setup

From: Lee Kwon, 06/03/09 02:24 PM

@David Fraser There is a way to delete the MySQL service. For some reason, the newer versions of MySQL don't delete the service after installation. All you have to do is manually go into the registry and delete the key. Reboot may be necessary. To access the registry, click the Start button, then in the search query where it asks you, "Start Search", type in "regedit". Open the registry editor and goto this folder: HKEY_LOCAL_MACHINE/SYSTEM/CurrentControlSet/Services All your services are listed in there. Just delete the service corresponding with MySQL.

ROR setup

From: David Fraser, 06/01/09 12:33 AM

Just like to say thank you. After a couple of days of drama and gumboot throwing I found these instructions. Degrading to MySQL ver 5.0.45 solved two major issues I was having. The first was that Webrick continued to crash. The second was that the ROR demo app did not work as expected. I spent hours trying to debug this and only in frustration did I move onto the Webrick crashing issue. DOH!!! :-) Now the demo blog app works as expected (as far as I have built it. BTW. I am using Vista Home Premium (I think that is it's name). One issue. I could not find a way to delete the existing MYSQL service in Vista. In the end I disabled it and created a new service for the new MYSQL installation under MYSQL5. This appeared to fail the MYSQL installation process but worked anyway. Thanks Lee for your advice about the socket number. I always ignored it but mainly through ignorance. Thanks again

RoR setup

From: Lee Kwon, 05/27/09 05:41 PM

@Luis Tavera rubygems 1.3.1 does work on vista. I just installed RoR on vista home premium (64bit) after days of failure. This walkthrough is actually very helpful (and the only one that worked for me). I pretty much followed the instructions listed here, though I didnt install subversion or git. A few notes to people still having trouble installing RoR on vista(x64). 1) Install the MySQL 5.0.45 32-bit version. I tried installing the 64-bit and it somehow didn't work right. 2) When do install MySQL, make sure during the config wizard, u check the "Include the BIN directory in Windows PATH". This is essential because RoR requires the libmysql.dll. If you have the mysql bin directory in the path variable, you dont have to copy and paste the dll file into the ruby/bin folder. 3) When you edit the database.yml file, don't specify the socket number. You may get a fixnum to string error. All you need is the database type, database name, username, and password.

rubygems-1.3.1 not working on vista

From: Luis Tavera, 04/06/09 06:33 PM

It seems that version 1.3.1 of gems does not work off the box for vista. I did gem update --system and ended up with a non-working gem command. I then uninstalled and reistalled ruby, downloaded, extracted the files, and ran ruby setup.rb

RoR-mySQL setup on Vista Home Premium (64-bit)

From: Ross MacLeod, 04/02/09 04:46 PM

I made it thru lesson 9 okay. Then, after trying to integrate mySQL 5.1.x, I spent days struggling with my development environment on Vista Home Premium (64-bit). I finally got it working; here's what I did: * Deleted all test apps, uninstalled mysql and ruby. * Cleaned up non-existent dirs from PATh Following Webvanta's script * Used Ruby one-click installer - windows, 1.8.6-27 Release Candidate 2, 19Nov08 * Installed mySQL v5.0.45, 32-bit version, Microsoft Windows 32. (Windows Installer format) (6 Jul 2007, 22.9M) The "MySQL Server Instance Configuration Wizard" did not run correctly. After reboot, and after explicit launch of C:\Program Files (x86)\MySQL\MySQL Server 5.0\bin\MySQLInstanceConfig.exe. ...the final 'Execute' button failed on 'Security setting'. Re-launching MySQLInstanceConfig.exe then allowed selection of 'reconfigure instance' and enabled proper reset of mySQL root password. * Installed rails capistrano mongrel mongrel_cluster gems * Installed mySQL gem, with an error creating the docs. mySQL gem created okay. * created rails project with mysql -d mysql mysqltest * created mysql database "mysqltest_development" * edited database.yml to use "mysqltest_development" and new root password Then index.html's "About Your Application's Environment" link showed proper settings. After deleting index.html, the 'Routing Error' screen displayed as expected. Good to go.

Thank you!

From: Ben Ridout, 03/29/09 03:00 PM

The ruby.exe interpreter was crashing for me on Windows Vista whenever I refreshed a Rails page. Turns out it was due to MySQL. Following your instructions, I reverted back to a previous version (5.0.45) and now Ruby is solid. Thank you so much for this post. It helped me solve an issue that had me flustered for quite some time!


From: tnt, 03/12/09 09:04 PM

I was having trouble getting everything to work with rails and mysql. Finally, I uninstalled everything I had, and followed your instructions. Now it all works. Thanks for writing this article. PS the IDE I use is Aptana with RadRails.

Thx for sqlite suffix!

From: Johan Almberg, 01/25/09 02:34 AM

Thank you so much for posting the "--version 1.2.3" suffix Jason! Been stuck with this database error for like a day.


From: Karl Bishop, 01/24/09 10:23 AM

I just saw Mr Haupt's post stating "rails -d mysql projectname" should be used to configure mysql as the database and that works! So is there some way to set this up as the default? Cheers

What's with sqlite3?

From: Karl Bishop, 01/24/09 10:15 AM

I used this guide the other day and ran into these two errors that seem to be well known: 1) When logging in to "http://localhost:3000/" for the first time and clicking "About your application’s environment", I get: MissingSourceFile in LoginController#first no such file to load -- sqlite3 etc... 2) When running "gem install sqlite3-ruby" I get: ERROR: Error installing sqlite3-ruby: ERROR: Failed to build gem native extension. etc... Thanks to Jason Willis for his "--version 1.2.3" suffix to sort out sqlite3 and get me up and running. But why did I get these errors in the first place and shouldn't the database adapter be mysql?

On Vista, you need to start command line as Adminstrator

From: Bob Lakkakula, 11/25/08 03:39 PM

On Vista, you need to start command line as Adminstrator. Otherwise you may see these permission errors.

SQLite 3 Error Message - tried to validate approach

From: Jason Willis, 10/09/08 07:48 AM

I was giving the approach from the link provided ( a go but didn't get too far (don’t despair, keep reading). I was able to download the files and place in the c:\ruby\bin directory. :) Next, I tried to get the "gem install sqlite3-ruby" command to work without much luck at all. I tried in multiple command prompt windows (meaning just opening new ones), with and without admin rights and switching the directory to c:\ruby\bin … all attempts came back with the message seen below: Microsoft Windows [Version 6.0.6000] Copyright (c) 2006 Microsoft Corporation. All rights reserved. C:\Users\Jason>gem install sqlite3-ruby Building native extensions. This could take a while... ERROR: Error installing sqlite3-ruby: ERROR: Failed to build gem native extension. c:/ruby/bin/ruby.exe extconf.rb install sqlite3-ruby checking for fdatasync() in rt.lib... no checking for sqlite3.h... no nmake 'nmake' is not recognized as an internal or external command, operable program or batch file. Gem files will remain installed in c:/ruby/lib/ruby/gems/1.8/gems/sqlite3-ruby-1 .2.4 for inspection. Results logged to c:/ruby/lib/ruby/gems/1.8/gems/sqlite3-ruby-1.2.4/ext/sqlite3_ api/gem_make.out Then I found this approach to try from : gem install sqlite3-ruby --version 1.2.3 and got this: C:\Users\Jason>gem install sqlite3-ruby –version 1.2.3 Successfully installed sqlite3-ruby-1.2.3-x86-mswin32 1 gem installed Installing ri documentation for sqlite3-ruby-1.2.3- x86-mswin32… Installing RDoc documentation for sqlite3-ruby-1.2.3- x86-mswin32… Then I started the server in c:\learningrails_9>ruby script/server Checked my http://localhost:3000/pages/about and http://localhost:3000/pages/home pages and they are now rendering. YES! Now, should I upgrade the version? Although the pages seem to render, what am I not getting by having the latest version? Not sure, maybe you could shed some light on that. Right now, I will temporarily bask in this small victory…

RE: SQLite 3 Error

From: Christopher Haupt, 10/08/08 09:47 PM

Jason, all: I commented on this on the XP version of the article. I haven't had a chance to validate this approach, but "this blog post": walks through setting up sqlite3 on Windows. If anyone could give that a try and let us know if it works for them, I'll update the articles for both XP and Vista to put it in the main text. Good luck! -c ps: Alternatively, some people want to use a different DB (such as MySQL which we show in the article). Do do that, you can generate new Rails projects with the @rails -d mysql projectname@ option, for instance, to use MySQL.

SQLite 3 Error Message

From: Jason Willis, 10/08/08 06:00 PM

On a previous post (May 15, 2008) BitNami was suggested to install the above stack. I went through the install as listed in the post above and have the same sqlite 3 error message as Tim did below. I would like to resolve this error rather than reinstalling through BitNami. Can someone help me? Here is what the error looks like: MissingSourceFile in PagesController#home no such file to load -- sqlite3 RAILS_ROOT: C:/learningrails_9 Application Trace | Framework Trace | Full Trace This error occurred while loading the following files: sqlite3 Request Parameters: None Show session dump --- flash: !map:ActionController::Flash::FlashHash {} Response Headers: {"cookie"=>[], "Cache-Control"=>"no-cache"}

Comments on Vista implementation cookbook

From: Niels Norgaard, 08/19/08 09:37 AM

Adequate cookbook.

Install cookbook for Ruby-on-Rails on Vista

From: Niels Norgaard, 06/27/08 04:34 AM

Thank-you – it worked with ok IVP’s.

add the service manually if the install fails

From: bob eff, 06/07/08 02:24 PM

use the sc create command in a dos window to add the service:

sc create MySQL start= auto DisplayName= MySQL binPath= c:\program files\mysql\mysql server 5.1\bin\mysqld.exe

then if you need to alter any parameters, use the administrative tools/services utility

It was really ease Vista Install

From: Tim, 05/18/08 09:29 AM

Tim, Thanks a lot. I was using InstantRails, but now i install this package and everything just works the same and also i have mysql, apache and so on configured, that’s just great, thank you a lot. I only have to create my projects folder inside the RubyStack folder, cause it places it’s default projects folder in some very distant place

Easy Vista Install

From: Tim Morgan, 05/14/08 06:15 PM

Vista is a complex platform to install. Might I suggest an all in one installer, as BitNami Stacks? The Ruby stack will setup all you need here, apache, imagemagick, mysql, php, sqlite, and subversion.

Could'not manage to complete the lesson on Vista

From: Tim, 05/06/08 04:34 PM

It looks like something is not configured. I could’not see the versions of my gems on the index page. I follow the Steps in the tutor of how to run Rails on Vista and even reinstall to make sure i do everything right. Also no content in pages/home, it says MissingSourceFile in PagesController#home This error occurred while loading the following files: sqlite3

I really need you help guys…

RE: MYSQL Frustrations

From: Christopher Haupt, 04/29/08 09:01 AM

[Jason and I emailed offline] It looks like a reinstall/restart got Jason going. When first testing logging in with “mysql -p -u root”, regardless if you set a password, you are using the -p option and can just type return when prompted. If you can’t get in and you did set a password, try without (just hit return when prompted), as sometimes the installer setting might not stick. Just want to reiterate something from above. Currently MySQL and Vista are a little shaky together. The version I used above I was able to make work just fine on a clean Vista install. Later versions are known to fail and the forums have threads about that. When you do install, walk through all of the dialogs slowly: there are a lot of them and you want for the most part to select the default options. The steps I go through above are important too, as the interaction between MySQL, Vista’s security system, the Firewall, and any settings you change are very picky.

MYSQL Frustrations...

From: Jason Willis (RoRookie), 04/29/08 04:10 AM

I deleted, rebooted, redownloaded and still having issues…can anyone help please. :)

c:\MySQL>mysql -p -u root Enter password: ** ERROR 2003 (HY000): Can’t connect to MySQL server on ‘localhost’ (10061)


MySQL help needed please

From: RoRookie, 04/28/08 03:19 PM

Thanks for this … I was doing great until I tried the mysql. I have downloaded an installed, but have no idea if its working…so I tried to verify and couldn’t.

C:\>mysql -p -u root Enter password: ERROR 2003 (HY000): Can’t connect to MySQL server on ‘localhost’ (10061)

Logged in as same user/admin?

From: Christopher Haupt, 04/06/08 09:36 AM

The usual reason for this error is not being logged in as an Administrator user. Can you confirm that you are logged in as either the Administrator or as the user that originally installed Ruby (via One Click Installer?)? Are you able to install other gems?

RubyGems update

From: Desmond, 04/06/08 08:32 AM

C:\>ruby -v ruby 1.8.6 (2007-09-24 patchlevel 111) [i386-mswin32]

C:\>gem -v 0.9.4

C:\>gem update—system Updating RubyGems… Attempting remote update of rubygems-update ERROR: While executing gem … (Errno::EACCES) Permission denied – C:/Program Files/ruby/bin/update_rubygems.cmd

I haven’t been able to get past this. Any advice?


Sponsored By

New Relic Rails Performance Monitoring