Building Ruby, Rails, Subversion, Mongrel, and MySQL on Mac OS X

Update for Leopard Users: The Ruby on Rails for Leopard installation instructions can be found here.

This article is a major update to the older (but tried-and-true) post, Building Ruby, Rails, LightTPD, and MySQL on Tiger. Both Ruby, Rails, and their underlying infrastructure have come a long way in recent months, and this article will get you to a leaner, meaner Rails install in less time using fewer steps.

This article is updated on a regular basis as new versions of the software are released.

What follows are instructions for building and installing the following applications on Mac OS X 10.4 (Tiger) along with their supportive software. I’ve been told that these steps work just fine on Mac OS X 10.3 (Panther) as well, but I haven’t verified this myself, and your mileage may vary.

Compiling and installing these tools this way is well worth the effort, as the end result delivers an easy-to-upgrade, system-independent, stand-alone development platform that is impervious to potential problems that can be caused by system updates, operating system upgrades, etc.

By rolling our own from source this way, we also have full control over our environment. We know what’s installed and where, what version we’ve used, where it came from, and there’s no dependence on an external ports system and the breakage or issues that come from relying on others to manage our software.

These issues and additional background information about why one might roll their own tools in this fashion are detailed in the article, Using /usr/local/, which could be considered a prerequisite for this task.

About (Not) Removing Old Versions

One of the great things about building these particular apps from source like this is that we don’t need to worry about removing older versions. When we build the new ones, they will replace the older versions as needed, and your system will be up to date with just the latest, greatest software.

The Concept

Basically, what we’re going to do here is download a bunch of open-source tools (some of which rely upon each other to work), configure them, compile them, and install them, one by one, until we have everything we need for a Mac OS X machine to run Ruby on Rails.

What’s Needed

A few things are needed to get this going:

  1. Mac OS X 10.4 (and maybe 10.3)
  2. Xcode 2.4 or newer (this compiles the apps for us)
  3. Willingness to type commands into the Terminal application exactly as they appear here (cut-n-paste works too)
  4. A tasty beverage to enjoy while things compile

Note: Xcode is not installed by default on new Macs, but can be found on the Mac OS X install DVD/CD, or downloaded from Apple’s Developer Connection free of charge.

Another Note: These instructions assume that you’re using bash, the default UNIX shell for Mac OS X 10.4. If you don’t know what this means and haven’t done anything very special to change this, you’re fine. If you’ve taken specific steps to change the default shell to something other than bash (like tcsh for example), you’ll need to be figure out the right files and syntax to use when setting paths and environment variables, or switch back to bash. Sorry about that.

A Quick Warning

While it’s unlikely anything we do here might do any kind of damage to the system, it’s good advice to have a current backup of everything, just in case. I don’t take any responsibility for anything that results from following these instructions (good or bad). You’re following these instructions at your own risk.

A Note about sudo

We’ll be using the command sudo quite a bit, and lots of people wonder what it does. Put simply, the sudo command allows a user (in this case, you) to execute a command as the superuser, allowing you to become the omnipotent master of your computer one command at a time.

With great power comes great responsibility, so Mac OS X may prompt you for your password prior to executing your command. It may do this only once, or several times throughout this process. Just re-enter your password as needed.

A Terminal Situation

Open the Terminal application. It can be found in the /Applications/Utilities folder.

Each of the lines below appearing in monospaced type should be entered into Terminal, and be followed by the Return key. But everybody knew that already.


Do not skip this step! Most everything else will fail if you do.

Mac OS X, like other UNIX systems, uses something called a path to determine where it should look for applications on the command line (that is, when you’re using the Terminal app). The path is actually an environment variable, set by a special file that’s automatically executed when you open a new Terminal window.

We need to make sure that our path is set to look for files in /usr/local (the place where we’ll be installing the tools) before looking anywhere else. This is important.

To see if the path has been set properly, we can check the contents of the .bash_login file (the special file hidden in our home folder) for a PATH line using a text editor. TextMate, TextWrangler, BBEdit, and vi are all perfectly good options. To open the file with TextMate, for example, we can type:

mate ~/.bash_login

This will open the file if it already exists, or open a blank file if it doesn’t. Add the following line at the very end of the file:

export PATH="/usr/local/bin:/usr/local/sbin:/usr/local/mysql/bin:$PATH" 

Now save and close the file.

It doesn’t matter how many other lines there are in the file, or what they say or do. Just make sure that this line comes last and you should be fine.

To make sure the changes are picked up correctly, we now need to execute the file with the following command:

. ~/.bash_login

It’s likely there will be no response from the shell here, just the prompt, but that’s OK, the changes have been picked up and we’re ready to move on.

You can also close your Terminal and open a new one instead if you’d like.

Geek Note: You may have noticed that I’ve added MySQL to the path in the line above. That’s because most users will be installing MySQL later in this tutorial. If you’re the type to want to use something like SQLite or PostGreSQL as your database instead of MySQL, you can feel free to omit the /usr/local/mysql/bin: bit from the line above, and replace it with the path to the database of your choice. If this note doesn’t make sense to you, even if you don’t plan to install MySQL later, just keep on going … the extra bit in the path statement won’t affect you at all.

Setting Up

I like to create a folder to contain all of the downloaded files and their respective build folders. I tend to keep this folder around indefinitely. Source code doesn’t take up much space, and it’s useful to refer back to later to remind yourself of previous installation details or techniques, installed versions, for a fast install at a later time, or in case you want to uninstall something.

For these examples, we’ll create a folder called src in the /usr/local section of the filesystem, and change directories into that folder. It will be our workspace for everything we do here:

sudo mkdir -p /usr/local/src
sudo chgrp admin /usr/local/src
sudo chmod -R 775 /usr/local/src
cd /usr/local/src

You’ll download and compile everything in this new folder.


Now we’re ready to start the real work. Just type (or cut-n-paste) each one of the following lines into Terminal, one by one. When one line finishes (some will take a while and dump a lot of information to the screen), enter the next one.

As mentioned above, the first time you run the sudo command (and possible again later), you may be prompted for a password. Just enter your regular password here, and the process will continue.

We’ll start off with Ruby, but before we can compile Ruby itself, we’ll build a supportive application called readline. The commands below handle downloading, unzipping, configuring, compiling, and finally installing the code. This “pattern” will become more familiar as you move through the install step by step.

curl -O
tar xzvf readline-5.1.tar.gz
cd readline-5.1
./configure --prefix=/usr/local
sudo make install
cd ..

If you get an error like the one below after typing the configure command:

checking whether make sets $(MAKE)... no
checking for gcc... no
checking for cc... no
checking for cc... no
checking for cl... no
configure: error: no acceptable C compiler found in $PATH

This means that you did not follow the instructions and don’t have Xcode installed.

If you saw lots of text fly by but didn’t get that error, it means that everything went well, and we can move on to building and installing Ruby itself.

curl -O
tar xzvf ruby-1.8.6.tar.gz
cd ruby-1.8.6
./configure --prefix=/usr/local --enable-pthread --with-readline-dir=/usr/local --enable-shared
sudo make install
sudo make install-doc
cd ..

If you saw lots of text fly by but didn’t get that error, it means that we should now have a brand new Ruby installed.

We can verify this (as well as a correct path setting) by typing the following command:

ruby -v

You should see something like this:

ruby 1.8.6 (2007-03-13 patchlevel 0) [i686-darwin8.9.1]

Don’t worry about the text in the parenthesis or brackets, those just provide detail about your system architecture which isn’t important here. What is important is that you see ruby 1.8.6. This means you’ve got the new version of Ruby installed and in your path, and you’re good to go.

If you see something like this:

ruby 1.8.2 (2004-12-25)

Then either your install failed, or you didn’t correctly set your path in the beginning (maybe you didn’t reload your .bash_login script or restart Terminal). Go back and check your work.


RubyGems is a handy command-line tool for managing the installation of Ruby packages, like Rails and Mongrel.

curl -O
tar xzvf rubygems-0.9.2.tgz
cd rubygems-0.9.2
sudo /usr/local/bin/ruby setup.rb
cd ..

Ruby on Rails

With RubyGems installed, Rails is a simple, one-line install:

sudo gem install rails --include-dependencies

If you see an error message like this:

/usr/local/bin/gem:3:in `require': No such file to load -- rubygems (LoadError)
from /usr/local/bin/gem:3

It means you didn’t set your path as instructed in the very first step. Go back to the beginning and run that step again, then retry this step.


Mongrel is a fast, stand-alone HTTP library and server for Ruby. It allows you to run your Rails applications without having to compile or use other applications (like FastCGI, SCGI, LightTPD, or Apache).

Even better, Mongrel is also a gem. Type this command:

sudo gem install mongrel --include-dependencies

You’ll be prompted to select the appropriate gem for your platform, and you’ll be shown a list something like this one:

Select which gem to install for your platform
 1. mongrel 1.0.1 (ruby)
 2. mongrel 1.0.1 (mswin32)
 3. mongrel 1.0 (mswin32)
 4. mongrel 1.0 (ruby)
 5. Skip this gem
 6. Cancel installation

Although version numbers may be different, you should always select the one closest to the top of the list that ends with “(ruby)” … this is usually the first option. Just type the number and press enter.

Subversion (Optional)

Subversion is an open-source version control system. It remembers every change ever made to the files and directories in your projects. This allows you to recover older versions of your data, or examine the history of how your data changed. You can read more about Subversion (svn) in the online Subversion book.

While it’s not mandatory to have svn running in order to use Rails, it’s highly recommended. It’s used by the Rails team for distribution management, by most web hosts for deployment (via Capistrano), and by most Rails developers to manage their code.

curl -O
curl -O
tar xzvf subversion-1.4.3.tar.gz
tar xzvf subversion-deps-1.4.3.tar.gz
cd subversion-1.4.3
./configure --prefix=/usr/local --with-openssl --with-ssl --with-zlib
sudo make install
cd ..


Capistrano is a utility which may be used to automate the deployment of your Rails applications. Many Rails applications and webhosts require it, and while this is technically an optional step, it’s simple, fast, and highly recommended. You can get the latest version of this gem like this:

sudo gem install capistrano --include-dependencies

I also recommend installing termios, a gem that’s a wrapper for the UNIX termios command, which will prevent passwords you enter in Capistrano from being displayed in your Terminal for all to see.

sudo gem install termios --include-dependencies

Technically, you could stop right here. But most Rails applications need a database …


While it’s possible to compile and install MySQL ourselves, using the Mac OS X MySQL package is actually advantageous. Not only is the package-installer much faster and easier, but it includes a handy startup item and a preference panel, and the binary is tuned by the MySQL team for Mac OS X.

Even better, the package installs MySQL right into the /usr/local/ folder, just like it should!

The install still requires a few steps:

  1. Download the MySQL 5.0 package for OS X PPC or the MySQL 5.0 package for OS X Intel
  2. Double-click the drive image to mount it
  3. Locate the MySQL installer (a file named something like mysql-5.0.37-osx10.4-i686.pkg) and run it, authenticating as needed
  4. Double-click MySQLStartupItem.pkg, authenticate, and let it install
  5. Double-click MySQL.prefPane and install it, deciding whether to make it available to just the current user, or for all system users

Once the install is complete, start the MySQL server using the newly-installed control panel.

Note: MySQL installs with a default user of root using no password. If you care about the privacy of your data or computer, please read this page about MySQL usernames and passwords and set a good one.

MySQL Native Bindings Gem (Optional)

This step is an optional one, but the performance gains seem to make it worth the extra step.

We start with a command to install the gem:

sudo gem install mysql -- --with-mysql-dir=/usr/local/mysql

Just like the Mongrel install, you might see a prompt asking you which gem to install:

Select which gem to install for your platform
1. mysql 2.7.3 (mswin32)
2. mysql 2.7.1 (mswin32)
3. mysql 2.7 (ruby)
4. mysql 2.6 (ruby)
5. Skip this gem
6. Cancel installation

Again, just like the Mongrel install, we’ll want to pick the option closest to the top that ends in “(ruby)”. In the example above, we’d want to select option 3.

You’ll see some text scroll by and when it’s done, you’ll have built native MySQL bindings, which should help make database operations a bit faster.


There’s an issue with the current version of MySQL and the latest Ruby. Fortunately, this is easily fixed with the following command in Terminal:

sudo install_name_tool -change /usr/local/mysql/lib/mysql/libmysqlclient.15.dylib /usr/local/mysql/lib/libmysqlclient.15.dylib /usr/local/lib/ruby/gems/1.8/gems/mysql-2.7/lib/mysql.bundle

You may be prompted to re-enter your password when you run it.

We’re Done

Congratulations, you now have a custom-built, properly located installation of Ruby, Ruby on Rails, MySQL, Mongrel, and Capistrano!

If you’re new to Rails and just want to create a sample app to see this all working, try this:

rails testapp
cd testapp

This will create a basic Rails app in a folder called testapp in your current folder (probably /usr/local/src if you’re doing this where the last step left off).

If all goes well, you’ll get some output that looks like this:

=> Booting Mongrel (use 'script/server webrick' to force WEBrick)
=> Rails application starting on
=> Call with -d to detach
=> Ctrl-C to shutdown server
** Starting Mongrel listening at
** Starting Rails with development environment...
** Rails loaded.
** Loading any Rails specific GemPlugins
** Signals ready.  TERM => stop.  USR2 => restart.  INT => stop (no restart).
** Rails signals registered.  HUP => reload (without restart).  It might not work well.
** Mongrel available at
** Use CTRL-C to stop.

You can now check out your new app by clicking or pasting this link in your browser of choice: http://localhost:3000

What Else?

To do any real work with your new app, you’ll want to create a database for it. The Rails convention is that the database will take the same name as the name you specified when the app was created (in this case, “testapp”).

You’ll need to first start up MySQL, and then create a database. While you can start MySQL using the control panel you installed earlier, it can also be started using the command line:

sudo /Library/StartupItems/MySQLCOM/MySQLCOM start

You won’t have to run this command again, because the startup item you installed for MySQL will make sure it’s running the next time you boot your Mac. With MySQL running, you can create a new database for the test application:

mysqladmin -uroot create testapp_development

If you created a password for MySQL, you’ll need to add the -p option to the command above and you’ll be prompted for your password.

The rest is up to you. Good luck, and have fun with Rails!

More articles in the Archive →