Setup Ruby On Rails on
macOS 10.12 Sierra

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 macOS 10.12 Sierra.

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.0
rbenv global 2.5.0
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.1.4

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.1.4

We're going to install sqlite3 from homebrew because we can't use the built-in version with macOS Sierra without running into some troubles.

brew install sqlite3

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:
brew services start mysql

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:
brew services start postgresql

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.


Noel Hwande (730 XP) on

Thanks for posting this, Chris. Did you face any issues with Nokogiri when installing the Rails gem?

Chris Oliver (159,840 XP) on

I haven't actually tested this personally just yet. :) I've got reports it worked great. Are you having issues with it?

Noel Hwande (730 XP) on

No worries :) Yeah and I think its a Nokogiri issue and its happening while I'm trying build a new app.

McGBob on

Hi Noel, I read your post above with great interest, since i've been trying to debug this issue the last 2-3 hours :(.

Any clues, did you manage to resolve this?

Ryan Crispin Heneise on

I experienced issues similar to this when installing Nokogiri:

xcode-select --install

prior to installing Nokogiri worked for me.

Utehn Sorsiang on

An error occurred while installing libv8 (, and Bundler cannot continue.
Make sure that `gem install libv8 -v ''` succeeds before bundling. <<<< don't work after i run bundle install

Yonghun Jeong on

have you solve the problem?
I got encounter the same situation.

thanlanuot on

I have solved this problem by those:

brew uninstall v8

gem uninstall libv8

brew install v8

gem install therubyracer

gem install libv8 -v -- --with-system-v8

Mariusz Głuch on

I have problem with 10.12 sierra :( rbenv not command found
If you want install RoR on macOS 10.12 Sierra you must update Command Line Tools

Иван Лещинский on

This commands helped me:
`brew install libxml2 libxslt`
`gem install nokogiri -v '' -- --use-system-libraries --with-xml2-include=/usr/local/opt/libxml2/include/libxml2`

pedro catré on

this might be preferred though
brew unlink xz; bundle install; brew link xz
read here:

Evgeny Cherpak on

make sure you have selected to use Xcode 8 command tools otherwise it won't work

Milton Spalburg on

i get

cat: ˜/.ssh/ No such file or directory

RowDog on

Me too. I eventually figured out to just type a file name with .pub extension and not to follow their instructions.

Milton Spalburg on

solved it i gave the file a name initially...

Milton Spalburg on

ok solved my ssh public key issue but now i m trying to launch mysql and the LaunchAgents in my path i find is a file not a directory...

Milton Spalburg on

and yes if i open the file i do see the entry however my terminal gives me the message...

Yonghun Jeong on

Guys, I have a problem. When I run rbenv install 2.3.1, it stops on this line.
^Cappleui-iMac:~ apple$ rbenv install 2.3.1
Downloading ruby-2.3.1.tar.bz2...
Installing ruby-2.3.1...

I installed Xcode not command line but I fully updated it.

Does anyone can help me?

Yonghun Jeong on

Actually, it works. It requires some time. So never mind!

ilias on

hello there,

I receive an error whenever I try to run the server or use the "rake db:create" command.
I'm using mysql db , tho

Chris Oliver (159,840 XP) on

There's actually a bug right now (in the last 2 hours) with the thor gem causing problems in new apps. Try this:

Melissa Khat on

When I try to run rbenv rehash, I get this error:

dyld: Library not loaded: /usr/local/opt/readline/lib/libhistory.6.dylib
Referenced from: /usr/local/bin/bash
Reason: image not found
Abort trap: 6

Not finding anything very helpful right now. Has anyone run into this issue? I just installed macOS Sierra and updated Ruby, Rails, rbenv...

Ayul Choi on

My English is not so good but your explanation is very clear to me! thanks a lot!

Robert Saunders (710 XP) on

I ran the command:

echo 'if which rbenv > /dev/null; then eval "$(rbenv init -)"; fi' >> ~/.bash_profile
source ~/.bash_profile

And now everytime I open a terminal window I am getting the below at the top of my window:

-bash: /Users/robertsaunders/.bash_profile: line 2: syntax error near unexpected token `source'
-bash: /Users/robertsaunders/.bash_profile: line 2: `if which rbenv > /dev/null; then eval "$(rbenv init -)"; fi source /Users/robertsaunders/.bash_profile'

Please help!

andrew on

After installing ruby the version doesn't see to update. does anyone have a suggestion? Running sierra 10.12.2

Audios-MacBook-Pro:shopify Audio$ rbenv install 2.2.5
Downloading ruby-2.2.5.tar.bz2...
Installing ruby-2.2.5...
Installed ruby-2.2.5 to /Users/Audio/.rbenv/versions/2.2.5\
Audios-MacBook-Pro:shopify Audio$ rbenv global 2.2.5\
Audios-MacBook-Pro:shopify Audio$ ruby -v
ruby 2.0.0p648 (2015-12-16 revision 53162) [universal.x86_64-darwin16]

andrew on

it might be worth adding this to the tutorial-
this needs to be in the last line of ~/.bash-profile

export PATH="$HOME/.rbenv/bin:$PATH"
eval "$(rbenv init -)"

Arif Jusoh on

Thanks @queglay:disqus , this is useful for me. Much appreciated

But my path was slightly different. I believe the path had changed since you reply

export PATH="$HOME/.rbenv/versions/2.4.2/bin:$PATH"

Travis on

Can you explain why we need to do this? Running into the same problem.
Edit: Do'h. I figured it out. I'm using zsh so I had to append it to my .zshrc file.

Dave Kliman on

This helped a lot! I just wish there were an easy way to know if I've just installed the latest versions of everything

Frank on

I had a problem in the Final Steps; i.e. running rails new myapp -d mysql. The problem was that mysql2 (0.4.5) was not built and installed. It asked me to run 'bundle install'. I then encountered another problem, ssl and encrypto libraries were not found in lib build path (it used /usr/local/Cellar/mysql/5.7.17/lib/). Setting up DYLD_LIBRARY_PATH won't work. To work around this, I copied all /usr/lib/*ssl* and /usr/lib/*crypto* to /usr/local/Cellar/mysql/5.7.17/lib/ and run 'bundle install' again and all worked. Just FYI and thanks.

Test Guy on

Using `rbenv install --list`, the latest version I get is 2.4.0preview2. How does one get the latest stable build like you? Total newb, need some help, I went to the rbenv installation guide on github and followed their instructions. Can we only install what we see in the results from the `rbenv install -l` command?

Chris Oliver (159,840 XP) on

What I usually do is I run "rbenv install 2.4.0" and it will say hey, this version is missing so update your ruby-build version and give you instructions on how to do that. Then running the install command should succeed then.

Test Guy on

Thanks, that worked! I updated ruby-build, that was the missing part.

Robert A. on

I had to run the rbenv commands with "sudo" otherwise it wouldn't even compile. Something about the -LD flags being wrong. That also forced "sudo" on the gem install command. But otherwise, everything went as advertised.

Robert Kisielewski on

was having problems with brew mysql when generating a new app using the mysql ....
error would thrown when 'Installing mysql2 0.4.5 with native extensions'
Errno::EACCES: Permission denied @ rb_sysopen -

what I had to do to solve that ...
sudo chown -R $(whoami) /Users/MYUSERNAME/.rbenv/ ....

tried milions things before ...that seemed to work ... I know kinda unwise sudo chown a directory ..but I got no other solution and that worked !!! hope it helps some future frustrated nerds like self ...

Marco Beffa (10 XP) on


Federico Moya on

Best guide ever !!! Thank you very much !! Absolutely no issues, keep doing stuffs like this !

Troy Borges on

This tutorial is fantastic, I was able to get my Rails to work!
Thanks to

Heri Anhari on

am nubi, asking for error Access denied for user 'root'@'localhost' (using password: NO)
i've tried update user and pass but this error still appear. what i have to update config/database.yml?

sorry for my bad english

Abdelmjid Lahmidi on

awesome, no issues following this tuto.

Mark Antony on

i can work with sublime text using this setup?

RowDog on

These instructions are terrible. It won't accept my SSH key as per the instructions to copy the output of "cat". This article is titled "Setup Ruby On Rails on macOS 10.12 Sierra" but they don't work. Please update!

John Harman on

Great instructions to get started! everything worked perfectly! Thanks!

Remy Ciuba on

I barely know html but I took the course for the command line at and that really helped.
googled around when I got stuck. Downloaded this to do the tutorial by Chris Pine, Learn to Program.

Maxim Kuba on

I get this problem after executing gem install rails -v 5.1.4

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

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

EnglishBC on

did you ever figure out this problem? i have it too...

[email protected] on

great manual, thank you so much!

Nikhila R (10 XP) on
I have XCode installed (mac OS 10.12.6), but when I try to install Homebrew, it tries to install Xcode command line tools and fails. I have not had this problem before trying to install Rails on earlier versions of Mac. Anyone has any suggestions to fix this problem?

ruby -e "$(curl -fsSL"
==> This script will install:
==> The Xcode Command Line Tools will be installed.

Press RETURN to continue or any other key to abort
==> Searching online for the Command Line Tools
==> /usr/bin/sudo /usr/bin/touch /tmp/
Can't connect to the Software Update server (srv-usva-jus01a).
==> Installing 
==> /usr/bin/sudo /usr/sbin/softwareupdate -i 
Software Update Tool

: No such update
No updates are available.
==> /usr/bin/sudo /bin/rm -f /tmp/
==> /usr/bin/sudo /usr/bin/xcode-select --switch /Library/Developer/CommandLineTools
xcode-select: error: invalid developer directory '/Library/Developer/CommandLineTools'
Failed during: /usr/bin/sudo /usr/bin/xcode-select --switch /Library/Developer/CommandLineTools

Login or create an account to join the conversation.