Install Ruby On Rails on
Mac OS X 10.9 Mavericks

A guide to setting up a Ruby on Rails development environment

This will take about 30 minutes.

We will be setting up a Ruby on Rails development environment on Mac OS X 10.9 Mavericks.

Older versions of OS X are mostly compatible so follow along as far as you can and then Google search for any problems you run into. There are plenty of people who have documented solutions for them.

First, we need to install Homebrew. Homebrew allows us to install and compile software packages easily from source.

Homebrew comes with a very simple install script. When it asks you to install XCode CommandLine Tools, say yes.

Open Terminal and run the following command:

ruby -e "$(curl -fsSL"

Choose the version of Ruby you want to install:

Now that we have Homebrew installed, we can use it to install Ruby.

We're going to use rbenv to install and manage our Ruby versions.

To do this, run the following commands in your Terminal:

brew install rbenv ruby-build

# Add rbenv to bash so that it loads every time you open a terminal
echo 'if which rbenv > /dev/null; then eval "$(rbenv init -)"; fi' >> ~/.bash_profile
source ~/.bash_profile

# Install Ruby
rbenv install 2.5.3
rbenv global 2.5.3
ruby -v

We'll be using Git for our version control system so we're going to set it up to match our Github account. If you don't already have a Github account, make sure to register. It will come in handy for the future.

Replace the example name and email address in the following steps with the ones you used for your Github account.

git config --global color.ui true
git config --global "YOUR NAME"
git config --global "[email protected]"
ssh-keygen -t rsa -C "[email protected]"

The next step is to take the newly generated SSH key and add it to your Github account. You want to copy and paste the output of the following command and paste it here.

cat ~/.ssh/

Once you've done this, you can check and see if it worked:

ssh -T [email protected]

You should get a message like this:

Hi excid3! You've successfully authenticated, but GitHub does not provide shell access.

Choose the version of Rails you want to install:

Installing Rails is as simple as running the following command in your Terminal:

gem install rails -v 5.2.1

Rails is now installed, but in order for us to use the rails executable, we need to tell rbenv to see it:

rbenv rehash

And now we can verify Rails is installed:

rails -v
# Rails 5.2.1

Rails ships with sqlite3 as the default database. Chances are you won't want to use it because it's stored as a simple file on disk. You'll probably want something more robust like MySQL or PostgreSQL.

There is a lot of documentation on both, so you can just pick one that seems like you'll be more comfortable with. If you're coming from PHP, you may already be familiar with MySQL. If you're new to databases, I'd suggest skipping to setting up PostgreSQL.


You can install MySQL server and client from Homebrew:

brew install mysql

Once this command is finished, it gives you a couple commands to run. Follow the instructions and run them:

# To have launchd start mysql at login:
ln -sfv /usr/local/opt/mysql/*plist ~/Library/LaunchAgents

# Then to load mysql now:
launchctl load ~/Library/LaunchAgents/homebrew.mxcl.mysql.plist

By default the mysql user is root with no password.

When you're finished, you can skip to the Final Steps.


You can install PostgreSQL server and client from Homebrew:

brew install postgresql

Once this command is finished, it gives you a couple commands to run. Follow the instructions and run them:

# To have launchd start postgresql at login:
ln -sfv /usr/local/opt/postgresql/*plist ~/Library/LaunchAgents

# Then to load postgresql now:
launchctl load ~/Library/LaunchAgents/homebrew.mxcl.postgresql.plist

By default the postgresql user is your current OS X username with no password. For example, my OS X user is named chris so I can login to postgresql with that username.

And now for the moment of truth. Let's create your first Rails application:

rails new myapp

#### If you want to use MySQL
rails new myapp -d mysql

#### If you want to use Postgres
# Note you will need to change config/database.yml's username to be
# the same as your OSX user account. (for example, mine is 'chris')
rails new myapp -d postgresql

# Move into the application directory
cd myapp

# If you setup MySQL or Postgres with a username/password, modify the
# config/database.yml file to contain the username/password that you specified

# Create the database
rake db:create

rails server

You can now visit http://localhost:3000 to view your new website!

Now that you've got your machine setup, it's time to start building some Rails applications.

If you received an error that said Access denied for user 'root'@'localhost' (using password: NO) then you need to update your config/database.yml file to match the database username and password.



Works like a fucking charm!


Hi, thanks for writing this guide. However, I got to executing the rails server and and got the following error:

FATAL: role "myapp" does not exist

Rails.root: /Users/BCN1002/myapp.

Any advice?


You need to change the config/database.yml username to match your database's username and password.


I don't see username in the config/database.yml file. where is it or what is its usual name?


It's inside your rails app; a file in the config directory.


thanks i figured it out!


so i found the database file but i don't know how to set the username and password and how to match it up with this file once it is set. is it the github password and username?


Thanks so much, I didn't encounter any problems!


I needed
ssh-add ~/.ssh/id_rsa

before connecting to github


$rails server -- the very last command just returns with the usage info for rails.


Make sure you run it inside of a rails app directory otherwise it will just display usage info.


Perfect. Thanks Chris!


Awesome article Chris!

Though i got stuck strangely at the command below.

git config --global "[email protected]"


Make sure that you type in the quotes by hand. It looks like the first quotes are an HTML formatted one but not the normal one.


just found some problems with rbenv, may be caused by my homebrew was not the latest version, it say i have rbenv install, but i got empty folders under ~/.rbenv, so i go to to clone it. and rbenv command works, then i found install comment missing, so i clone it by using : git clone ~/.rbenv/plugins/ruby-build , then everything works fine. BTW, i found some one says rbenv should be under ./.rbenv/shims, but i found it still use ~/.rbenv/bin, so just check that you cloned from github :)


So when you ran brew install those directories were empty? That's odd.

Gautam Doddamani

thank you so much worked perfectly...although the cat command wasn't required...another little should copy the public key not the private key...the one that starts with ssh-rsa..after generating the ssh key you can easily copy it onto your clipboard by typing:
pbcopy < ~/ .ssh/
and paste it in github!!


Great Tut thanks


couldn't get postgresql to work. Went back to mysql and it starting working again. Something about write permissions was hanging it up.


ERROR: While executing gem ... (Gem::FilePermissionError)

You don't have write permissions for the /Library/Ruby/Gems/2.0.0 directory

how i fix that?


this is the best tutorial about setting up ruby on rails (y)


Could not find a valid gem 'rails' (>= 0), here is why:

Unable to download data from - no such name (


Awesome! Had some small issues at first (when I did the Ruby -V thing, I kept getting my old Ruby version), but after the restart, smooth sailings. Thanks for the info!


Can you tell me how to fix that? I cannot use posgresql database. Here is the error I get ->

could not connect to server: No such file or directory Is the server running locally and accepting connections on Unix domain socket "/tmp/.s.PGSQL.5432"?


Try specifying the "host:" option so it doesn't try to connect through the socket.


Can you kindly explain me how to do that? Thanks Sir.


Change your config/database.yml to look like this:

adapter: postgresql
database: myapp_dev

Rename the database to whatever you want to call your app's database and also make sure to change your postgres username to your username. And last, but not least, make sure postgres is running.


I got this error ->
could not connect to server: Connection refused Is the server running on host "" and accepting TCP/IP connections on port 5432?
Any idea to fix ,Sir?


Sounds like you don't have postgres running. Follow the steps in the postgres section again to make sure you got them (especially the launchctl one.)


I'm having a little trouble with getting rbenv configured. I have followed all of the commands, but when i try to run rbenv install 2.1.2, I'm getting install command not found.

MacBook-Pro:~ munkie$ rbenv

rbenv 0.4.0-98-g13a474c

MacBook-Pro:~ munkie$ rbenv install 2.1.2

rbenv: no such command `install'

MacBook-Pro:~ munkie$


That command is provided by ruby-build. Make sure you didn't miss any of those steps.


re-running the brew commands seems to have resolved the issue


when I run:
`gem install rails`

I got this error:

ERROR: Could not find a valid gem 'rails' (>= 0), here is why:

Unable to download data from - Errno::ETIMEDOUT: Operation timed out - connect(2) for "" port 443 (

What should I do now?


rails new application -d postgresql
Can't initialize a new Rails application within the directory of another, please change to a non-Rails directory first.


I had received an issue with SSL breaking the ruby build. All I had to do was use brew to uninstall SSL and reinstall the latest version.

Error: The Ruby openssl extension was not compiled. Missing the OpenSSL lib?


> brew uninstall openssl
> brew update
> brew install openssl

Great article, thanks!


That's no fun. Do you still have the error to share?


Just added, thanks!


I get a "No such file or directory" when using cat ~/.ssh/

Any ideas?


I was prompted to add the SSH to a file, (not pictured in the tutorial steps) which I tried doing several times with different naming schemes, but couldn't get it to work. Finally I just re-ran the commands and hit 'enter' at the ask-for-filename step, and from there following the tutorial commands verbatim worked for me.

So if you tried to add it to a different file, don't - just go with the defaults. =)


SSH does get pretty cumbersome when you've got a bunch of different keys. Here's some ideas on how to make it better:




Worked for me.
Thank you.


Great walk through, worked perfectly!





Ran into the following Error:

The `brew link` step did not complete successfully
The formula built, but is not symlinked into /usr/local
Could not symlink include/mysql
/usr/local/include is not writable.

Any comments or help on this would be most appreciated!


Your problem is:

/usr/local/include is not writable.

I think that should be owned by your user. Mine is

drwxr-xr-x  232 chris  admin   7888 Sep 26 14:24 include

I imagine fixing permissions and reinstalling mysql will do the trick.


I get to the point where I'm loading mysql and then get errors:

launchctl load ~/Library/LaunchAgents/homebrew.mxcl.mysql.plist

launchctl: Couldn't stat("/Users/myusername/Library/LaunchAgents/homebrew.mxcl.mysql.plist"): No such file or directory

nothing found to load

any hints?


(and thanks for this page; I'm looking forward to being up and running soon. Much closer already thanks to you)


Working! Thank you!


great tutorial!!


Thanks a lot, it was always a struggle to get a Rails app to work with `pg` before. Not anymore!


Thanks for this!


I'm stuck on the final steps of the installation, I went to create a new rails app. Results are below. I clicked (yes) for everything after the conflict below, and then db:create after

Pears-MacBook-Pro:~ Pear$ rails new tryout -d postgresql


identical README.rdoc

identical Rakefile


identical .gitignore

conflict Gemfile

Overwrite /Users/Pear/tryout/Gemfile? (enter "h" for help) [Ynaqdh]

There was also
Pears-MacBook-Pro:orange Pear$ rake db:create

Could not find gem 'pg (>= 0) ruby' in the gems available on this machine.

Run `bundle install` to install missing gems.

I used homebrew and i'm on mavericks 10.9, i'm trying to find a way to add the rvm, and i've used stack overflow beforehand.

thinknig about just uninstalling everything and resetting everything up if I can't find an answer as i've been working on this for the last few hours.

Any help would be appreciated.



You need to run 'bundle install' as it mentioned there. You set up a new Rails app with a different database. That means you've got a new database adapter gem to use but haven't installed it yet. bundle install will do that for you.


thanks for the repy chris, I should've mentioned that I did try bundle install also yesterday(though, with sudo), and the subsequent steps of using gem install pg '0.17.1', but to no avail. this is why i posted up thoughts. i'm still a new user to the mac environment and rails so i'm sort of learning on the fly.

Pears-MacBook-Pro:cic Pear$ Your user account isn't allowed to install to the system Rubygems.

> You can cancel this installation and run:


> bundle install --path vendor/bundle


> to install the gems into ./vendor/bundle/, or you can enter your password

> and install the bundled gems to Rubygems using sudo.



Pears-MacBook-Pro:cic Pear$ bundle install

Fetching gem metadata from

Resolving dependencies...

Using rake 10.3.2

Using i18n 0.6.11

Using json 1.8.1

Using minitest 5.4.2

Using thread_safe 0.3.4

Using tzinfo 1.2.2

Using activesupport 4.1.7

Using builder 3.2.2

Using erubis 2.7.0

Using actionview 4.1.7

Using rack 1.5.2

Using rack-test 0.6.2

Using actionpack 4.1.7

Using mime-types 2.4.3

Using mail 2.6.3

Using actionmailer 4.1.7

Using activemodel 4.1.7

Using arel

Using activerecord 4.1.7

Using bundler 1.7.4

Using coffee-script-source 1.8.0

Using execjs 2.2.2

Using coffee-script 2.3.0

Using thor 0.19.1

Using railties 4.1.7

Using coffee-rails 4.0.1

Using hike 1.2.3

Using multi_json 1.10.1

Using jbuilder 2.2.4

Using jquery-rails 3.1.2

Gem::Ext::BuildError: ERROR: Failed to build gem native extension.

/System/Library/Frameworks/Ruby.framework/Versions/2.0/usr/bin/ruby -r ./siteconf20141105-513-x567l4.rb extconf.rb --with-pg-config=/Applications/

Using config values from /Applications/

sh: /Applications/ No such file or directory

sh: /Applications/ No such file or directory

checking for libpq-fe.h... yes

checking for libpq/libpq-fs.h... yes

checking for pg_config_manual.h... yes

checking for PQconnectdb() in -lpq... no

checking for PQconnectdb() in -llibpq... no

checking for PQconnectdb() in -lms/libpq... no

Can't find the PostgreSQL client library (libpq)

*** extconf.rb failed ***

Could not create Makefile due to some reason, probably lack of necessary

libraries and/or headers. Check the mkmf.log file for more details. You may

need configuration options.

Provided configuration options:



























extconf failed, exit code 1

Gem files will remain installed in /var/folders/jc/fx43z95j349cv01h3spj4dpr0000gn/T/bundler20141105-513-znjfu2/pg-0.17.1/gems/pg-0.17.1 for inspection.

Results logged to /var/folders/jc/fx43z95j349cv01h3spj4dpr0000gn/T/bundler20141105-513-znjfu2/pg-0.17.1/extensions/universal-darwin-13/2.0.0/pg-0.17.1/gem_make.out

An error occurred while installing pg (0.17.1), and Bundler cannot continue.

Make sure that `gem install pg -v '0.17.1'` succeeds before bundling.


I think you may need to install postgres because it can't find libpq in your logs there: Can't find the PostgreSQL client library (libpq)

brew install postgresql

Also with this set up, you should never have to use the sudo command. If you use it, you're likely to cause permissions problems where files are owned by root and not your user. It causes a chain effect where everything starts to require sudo which is bad. Basically don't ever run sudo and if you run into problems, there's a different problem which can be fixed without sudo. :)


eeek, should i have done the > bundle install --path vendor/bundle line instead? and postgresql was already installed also, as noted below.

Warning: postgresql-9.3.5_1 already installed


You should just be able to do bundle install without any options and it should work.

Now that I'm looking at your logs again, it looks like you installed so it isn't looking at homebrew's Postgres. I'm sure that's the problem. One thing you can try is to uninstall and see if it gets resolved.

If you want to keep with that, there is lots of people talking about it with some instructinos that probably work:


I have been using homebrew the whole time. I've gone through some of those stack overflow posts yesterday and again just now. But nothing yet. ARGH. thank you for your help though.


Always something! It looks like you've got something configured to point to that directory so maybe you set an environment variable while following one of those posts. That's definitely possible. You might need to just unset some environment variables then.


One thing to keep in mind, at least with OSX, if you can install it with Homebrew, definitely do that. It's easily the best way to install things and you rarely will have trouble with it.


I've never used postgresql in a rails app. I'm getting errors, here is a gist:


not sure how to configure postgres in the yml file


I did the github stuff. never was shown a ssh keycode or whatever.
heres the stuff

jasons-MacBook-Pro:~ prince$ ssh-keygen -t rsa -C "[email protected]"

Generating public/private rsa key pair.

Enter file in which to save the key (/Users/prince/.ssh/id_rsa): desktop

desktop already exists.

Overwrite (y/n)? n

jasons-MacBook-Pro:~ prince$


When you type "desktop" it thinks you want to use that as the filename. You want to type a full folder and filename. It suggests (and I do too) saving it to /Users/prince/.ssh folder with the name of id_rsa. That's the default and you can go with that because SSH will check there automatically to find keys. If you don't save it there, then you will need to specify where your key is every time you use SSH.


Or just use thoughtbot's laptop repot. (for mac users)


Their repo is fantastic for people familiar with how to setup Ruby. This guide's goal is to teach newcomers the basics.


for install Brew i'm need Ruby, for install Ruby i'm need Brew(((


Haha! Actually OSX comes with an older version of Ruby. We use that to install Homebrew so we can make installing a ruby version manager easily.


but, i'm remove ruby from OS accedentally. Install it again was not ease...


Hi I got this message after I ran: gem install rails -v 4.2.1

Fetching: i18n-0.7.0.gem (100%)

ERROR: While executing gem ... (Gem::FilePermissionError)

You don't have write permissions for the /Library/Ruby/Gems/2.0.0 directory.

can you tell me what I need to do?


This is basically saying that you're not using the rbenv version of Ruby and you're using system Ruby which you don't want to do.

Try restarting your terminal and double check your ran all the commands. The output you should get from the "which ruby" is something like this "/Users/chris/.rbenv/shims/ruby" when it is set up correctly.

Carlos Castellanos

I have the same problem , but i´m using rbenv , :( ruby -v put 2.2.2 but when i run bundle install

Bundler::GemspecError: Could not read gem at /Library/Ruby/Gems/2.0.0/cache/json-1.8.1.gem. It may be corrupted.

An error occurred while installing json (1.8.1), and Bundler cannot continue.

Make sure that `gem install json -v '1.8.1'` succeeds before bundling.

i tried "which ruby" and the result was /Users/Carlos/.rbenv/shims/ruby

any idea?


just say -> sudo gem install rails -v 4.2.1
It worked fine with that.


hi, i went through these instructions everything worked, then i got to the end and discovered that the program that i am attempting to run is dependant on ruby 1.8.7 instead of 2.2.2. How would I uninstall v 2.2.2?


Don't worry about uninstalling it because you might want to use 2.2.2 in the future. You installed a version manager so you can have multiple copies at once.

Just do this to install 1.8.7:

rbenv install 1.8.7
rbenv global 1.8.7
ruby -v


Hey, thanks, i had to install: brew tap homebrew/dupes ; brew install apple-gcc42
version manager to be able it to install 1.8.7-2012.02 but it worked.


everything seems to have worked but I can't load http://localhost:3000. I'm using OSX 10.9 and wondering if there s a firewall problem. Is there and how would I fix that?


I am getting the below error..rake db:create

rake aborted!
LoadError: Please install the mysql2 adapter: `gem install activerecord-mysql2-adapter` (can't activate mysql2 (~> 0.3.10), already activated mysql2-0.4.1. Make sure all dependencies are added to Gemfile.)

Tasks: TOP => db:create
(See full trace by running task with --trace)

Please help on this issue...


its fixed.. mysql version issue.. thanks friends..


how did you fixed it? which version do u use now?


you can find the solution over here..


I am getting this error:how should I fix it?
specified 'sqlite3' for database adapter, but the gem is not loaded. Add `gem 'sqlite3'` to your Gemfile (and ensure its version is at the minimum required by ActiveRecord).Please be specific.


when I try this command: mysql -u root -p

Enter password:

ERROR 2002 (HY000): Can't connect to local MySQL server through socket '/tmp/mysql.sock' (2)


I tried to install mysql already three times. I even removed all packages with brew and started from scratch. Nothing works. I get a whole lot of unreadable errors when i tried to install mysql via brew. please help what to do:
[email protected] thank you.

here is the whole error report:

Last 15 lines from /Users/alexander/Library/Logs/Homebrew/mysql/post_install.01.mysqld:
2017-01-26 02:51:00 -0800


2017-01-26T10:51:00.896146Z 0 [Warning] TIMESTAMP with implicit DEFAULT value is deprecated. Please use --explicit_defaults_for_timestamp server option (see documentation for more details).
2017-01-26T10:51:00.902385Z 0 [ERROR] --initialize specified but the data directory has files in it. Aborting.
2017-01-26T10:51:00.902439Z 0 [ERROR] Aborting

Warning: The post-install step did not complete successfully
You can try again using `brew postinstall mysql`
==> Caveats
We've installed your MySQL database without a root password. To secure it run:

To connect run:
mysql -uroot

To have launchd start mysql now and restart at login:
brew services start mysql
Or, if you don't want/need a background service you can just run:
mysql.server start
==> Summary
🍺 /usr/local/Cellar/mysql/5.7.17: 14,226 files, 456.3M, built in 14 minutes


if someone has errors with db:rake not working, here is the solution:

Login or create an account to join the conversation.