Setting up Rails on Windows XP

This guide walks you through setup instructions for preparing a Windows XP 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 XP operating system with up-to-date service patches applied (SP2 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.

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 the Run… menu item, and then typing cmd 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. After downloading the community edition (open source) Windows Essentials setup program, double click it to start:

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.51a-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.


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 ready 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 higher 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. There is a trial version available if you want to test it out.

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)

Where to go from here?

From: satish, 10/09/11 10:28 PM

I have followed this article.And all goes well.Could you tell me please, what do next now, to learn rail

How do I start ruby on Rails on windows XP platform

From: Leon H, 04/18/11 07:12 AM

I have downloaded into C directory. Thanks PS!! I am a newbie to RoR


From: AnotherUselessTutorial, 02/08/11 04:35 AM

Installing Ruby works fine, But rails no. Why? Why Subversion? I dont see anything that to do with Rails. Do I?

How to Uninstall

From: wayne, 11/16/10 11:18 AM

I have installed One click Ruby and Gems. But then I discovered Aptana Studio and installed that also. Now how do I uninstall your version or Do I have to? Thanks.

downloads behind firewall issues

From: sharath, 11/09/09 05:26 AM

a separate section heading "if you are behind firewall" giving the errors user encounters & how to overcome them will be helpful

Command line interface path info not updated after re-installation of Ruby ?

From: Terje Bohler, 10/06/09 01:04 AM

Hi. I had some initial problems with my Ruby installation (Win-XP), so I decided to uninstall+re-install. After this second downloading of ruby186-27_rc2.exe from, even the "C>ruby -v" (from a newly opened "cmd-window") didn't work ... I would appreciate any suggestions/cures very much (Yes, I know I can force/configure the PATH environment variable, but the above described symptoms may explain the general installation problems I have). Regards Terje

Just a simple thanks

From: Jamie, 08/13/09 03:40 PM

Thanks for taking the time to publish this. Everything went very smoothly. Much appreciated.

Just a simple thanks

From: Jamie, 08/13/09 03:40 PM

Thanks for taking the time to publish this. Everything went very smoothly. Much appreciated.

Gems from behind firewall

From: Michael Slater, 07/24/09 07:57 AM

Depending on what ports your firewall blocks, you may not be able to use gem install. You can download the gem files from and the install the downloaded files.

Problems with work firewall

From: Stefan, 07/24/09 02:37 AM

Hey there, I am having problems at the gem install rails step. I looks but can't find the files it needs at rubyforge. I am having to install this on a work laptop so the directories and firewall may be a problem. any help would be grately appreciated...oh so close to getting rails installed but oh so far. Thanks

From: Ryan, 07/15/09 09:47 PM

You guys are awesome

From: Badka, 07/02/09 07:19 AM

Tnx for the article. It was really useful.

installing Sqlite3 on windows XP

From: wajahat, 06/24/09 11:51 AM

this is what got me running sqlite3 on my machine to the point right on the mark and this command works: gem install --version 1.2.3 sqlite3-ruby

gem install command

From: Greg, 06/10/09 08:37 PM

I've just installed using Ruby186-27_rc2. I've reached the 'gem install' command and am getting an error. ERROR: While executing gem ... buffer error I imagine there's a setting somewhere that I can change to resolve this but I can't find it. Any clues?

Installing Ruby on Rais on Windows XP

From: Anand Deo, 01/22/09 01:08 AM

This is really a very helpful aritcle.

installing sqlite3 on windows xp

From: Steve, 01/02/09 09:44 AM

Later lessons use sqlite3 instead of mysql, so I tried to switch to sqlite3. The cmd gem install sqlite3-ruby doesn't work - says it requires nmake. Instead this command works: gem install --version 1.2.3 sqlite3-ruby The latest version did not get all updated for windows, apparently.

creating the mysql database

From: steve peterson, 11/12/08 07:46 PM

Note to other newbies like myself - if you have problems, go through these reader comments. To add to what was said already, this cmd seems to work when going through lesson 9, entered at the mysql prompt: create database learningrails_9_development CHARACTER SET 'utf8'; also, I had to add root's password that I keyed in during mysql installation - it went into config\database.yml and was intuitive.

finally Git client!

From: Vitaliy Khudenko, 09/10/08 03:47 AM

Thanks guys, I've finally got Git client installed on my Win XP. It works! I've been looking for the solution for quite a long time.

answer to lavanya

From: Vitaliy Khudenko, 09/10/08 03:22 AM

Before starting the app in a certain environment (development, test or production) you should create a DB itself with an appropriate name. Look at c:\lavya\config\database.yml for those names. The way of creating a DB is up to you. Also check the encoding option when creating a DB, as Rails default is UTF-8.

Unknown Database error when loading pages http://localhost:3000/pages

From: lavanya, 08/20/08 01:11 AM

I followed the set up instructions in Lesson 8 for Windows XP, then like in Lesson 9, at cmd prompt c:>rails -d mysql lavya c:>cd lavya c:/lavya>ruby script\generate controller pages home c:/lavya>ruby script\server when i load http://localhost:3000/pages, it shows " Mysql::Error in PagesController#index Unknown database 'lavya_development'" what could the problem be? I've been searching for solutions for the last two days... btw what is rake create:db for? I haven't used it...

Unknown Database error when loading pages http://localhost:3000/pages

From: lavanya, 08/20/08 01:11 AM

I followed the set up instructions in Lesson 8 for Windows XP, then like in Lesson 9, at cmd prompt c:>rails -d mysql lavya c:>cd lavya c:/lavya>ruby script\generate controller pages home c:/lavya>ruby script\server when i load http://localhost:3000/pages, it shows " Mysql::Error in PagesController#index Unknown database 'lavya_development'" what could the problem be? I've been searching for solutions for the last two days... btw what is rake create:db for? I haven't used it...


From: Michael Slater, 07/30/08 01:46 PM

I like SQLyog ( and Navicat (

best GUI for MySql

From: Nilesh, 07/30/08 09:55 AM

Hi Christopher and Michael. You both are doing excellent job in spreading Ruby on Rails knowledge. A big RoR for you both. I wanted to know which GUI will be best for MySql? Please let me know. Thanks :)


From: Gurvinder, 07/18/08 02:04 PM

Thankyou Guys for all of this.

RE: Using MySQL instead of SQLite

From: Guti, 06/20/08 09:17 AM

Easy! thank you very much!

Using MySQL instead of SQLite

From: Michael Slater, 06/18/08 10:43 AM

To use MySQL in a new Rails project, just add -d mysql when you create the application:

rails -d mysql myapp

RE: MissingSourceFile in Rails | change the default DB ?

From: Guti, 06/18/08 07:33 AM

Ooh! thanks that solved the issue. Great!

..And how could I change the default DB for Rails projects, from SQLite to MySQL ?

thanks again.

RE: MissingSourceFile in Rails

From: Christopher Haupt, 06/12/08 03:05 AM

Guti, the above instructions walk through setting up MySQL, which until the more recent versions of Rails 2 was the default DB (and for most production projects, is still the most common DB in use). For Rails 2.0.2 and newer, and for development/learning purposes, SQLite3 is the default DB in use. Windows does not come with SQLite pre-installed.

One blog link with instructions can be found here. We’ll provide our own version of an installation guide article in the future.

MissingSourceFile in Rails/infoController#properties

From: Guti, 06/11/08 08:47 AM

I’ve done all steps, one by one. And I’ve created a new project, I’ve started the server. In the browser, localhost:3000 says: MissingSourceFile in Rails/infoController#properties no such file to load—sqlite3 There’s something missing? or something more to configure? Thanks in advance

Minimum hardware

From: Michael Slater, 06/10/08 04:18 PM

Sameer, you should be able to run Ruby on Rails on even a low end Windows XP system as a development box, though I can’t say I’ve ever tried.

what minimum hardware do I need to run ruby on rails on windows XP

From: sameer, 06/07/08 11:49 PM

Hi Christopher,

I read your instructions above and it looks pretty good. I have worked on Mac OS, but never developed any ruby app in windows XP. Could you please let me know what is minimum hardware requirement to develop ruby application on Windows XP.

Thanks and looking forward to get response asap.


RE: Ruby command

From: Christopher Haupt, 05/29/08 07:55 AM

Sounds like the path wasn’t set up. Is the software actually getting into the directory you selected (C:\Ruby by default)? If you change directory into that area, and try to run the ruby command from there, does it work?

See the comments below for my note about setting the path properties.

Ruby command not working in command prompt

From: Ryan, 05/29/08 04:56 AM

I am unable to check the version of ruby or gems via the command line prompt. I downloaded and installed the One-click Ruby Installer (ver. 186-26). Am I doing something wrong? I also uninstalled then reinstalled. Any help would be greatly appreciated.

RE: Using InstantRails

From: Christopher Haupt, 05/27/08 01:49 AM

If InstantRails works for you, then absolutely go for it. All of these packages are being refined (frequently in some cases). You choice will often depend on how comfortable you are with the different set-up options. The all-in-one packages will be easiest, but may force you in to a set-up that is more constrained. The piece-meal installation approach is harder, but more flexible.

I’ve struck a middle ground approach with the articles as I believe it is important to understand the various pieces that make up the development environment and as you grow in knowledge, you’ll likely want to change some of them.

Certainly for the screencast series, pretty much any of these packages will work most of the time.

Using InstantRails

From: Mik, 05/26/08 10:52 PM

Jeff mentions InstantRails below… would there be a problem if I followed your course using that or would you recommend the set up in your article?

RE: Start Rails WInXP

From: Christopher Haupt, 05/17/08 01:31 AM

Joel: Did you get it from You’ll need to set up the rest of your environment (see the article) for Ruby, MySQL, RubyGems, etc., and of course you get Rails as part of those instructions. If you already have that stuff and just want the Rails framework, the zips on RubyForge are “ready to go” from what I recall. Just drop it into a development directory and you have an installed project you can start with. Rails itself is in the vendor/rails directory in the zip. Just change directory into the top level of the zip and you can start using that space.

Start rails WinXP

From: Joel Chisenga, 05/16/08 10:25 PM

Hey there, i downloaded zipped rails from how do i set it up

RE: Path Problems

From: Christopher Haupt, 05/16/08 06:16 PM

[jose] If you set your path up in the system environment preferences, they’ll stick around. Go to Start,then right click on My Computer, select Properties, select Advanced, Environment Variables, and in the bottom of that dialog, find System Variables, and select Path and press Edit. Add your complete paths here: e.g. C:\ruby\bin. Be sure to separate each path with a semi-colon.

Path problems in windows XP

From: Jose, 05/16/08 02:51 PM

Thanks for the clear up-to-date instructions. The best I have seen so far… But, I have a problem.

PROBLEM: For some reason my windows XP erases all directory paths as soon as I restart (e.g. ruby\bin\ and mysql\...\bin). Including mysql and ruby paths. Is there a file I can run that would set all the paths each time my system starts? Or is there a way to configure my windows XP so the directory paths are kept?. Also i noticed that each time I set a new path manually, all previous paths are erased. As you can imagine, I am unable to work like this. Please help! this is very frustrating…

Instant Rails?

From: Jeff, 05/09/08 04:02 AM

I’ve found Instant Rails ( to be very easy to set up. It’s Ruby, Rails, Apache, MySQL, and a bunch of other stuff all in one .zip file. Just unpack and run.

RE: IntelliJ Rails Plugin

From: Christopher Haupt, 05/06/08 02:14 AM

I don’t have a current copy of IntelliJ, so haven’t evaluated the Ruby/Rails plugin. From their site, it looks interesting. On Windows, I’ve been using the TextMate “port”: E TextEditor ( as well as Netbeans 6.1.

thx Christopher

From: Elopez, 05/04/08 09:39 PM

Thank you Christopher, your steps worked perfect for the offline machines, actually I tried both, I have a desktop with win xp, and a laptop with windows vista,I downloaded the gems for vista just to try it out. It is so many gems to download that sounds interesting by their names. What do you think about intellij plugin for rails?

RE: Setting up when you don't have an Internet Connection

From: Christopher Haupt, 04/29/08 03:23 AM

[Elopez] Yes, you can install on a disconnected machine. If your machines are the same architecture, you can grab your local gem cache (C:\ruby\lib\ruby\gems\1.8\cache on my machine). You can also download gems manually from places like, or use the command “gem fetch”. There are more complicated things you can do (including setting up local gem repositories and gem servers, but we’ll skip that). Once you have the gem files local and transfered to your offline machine, move into that directory and use “gem install gemname—local” where gemname is the gem(s) you wish to install.

setting up when you dont have internet connection

From: Elopez, 04/28/08 10:01 PM

Hi, Great article thank you guys for putting time to do this series that I am sure will help a lot of new rails programmers like me. I want to ask you is there a way to download the gems and install them in another machine (laptop) that does have internet connection.

great article!

From: unknown, 04/20/08 09:37 AM

This is a great article and helped me a lot!

Setting up Rails on Windows XP

From: AnotherDave, 04/07/08 06:25 AM

Following your instructions to the letter, and using the same versions of the same software, will not deliver a workable Rails system.

The first try, the installer puked on XP’s wonderful “Program Files” directory path. I don’t suppose it gave you any trouble at all. Second try, the installed programs failed to configure themselves for my spaceless c:\programs directory.

I suppose I’ll get this all sorted out someday, but then I supposed that about ten other installation tutorials would work, too.


Sponsored By

New Relic Rails Performance Monitoring