Setup Ruby On Rails on
Mac OS X 10.11 El Capitan

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.11 El Capitan.

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 https://raw.githubusercontent.com/Homebrew/install/master/install)"

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.1
rbenv global 2.5.1
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 user.name "YOUR NAME"
git config --global user.email "[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/id_rsa.pub

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

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

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.

MySQL

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.

PostgreSQL

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.



Discussion


Gravatar

Stop confusing people, there is a big problems with homebrew and El Capitan

Gravatar

had no problems

Gravatar

Orly? Homebrew works fine?

Gravatar

yea works fine for me

Gravatar

brew working for me but facing an issue while installing Rails

its shows an error like hile executing gem ... (Errno::EACCES)

Permission denied - /Library/Ruby/Gems/2.0.0/gems/nokogiri-1.6.6.2/.autotest

in the terminal

Gravatar
Zasheek Tamaris on

try running
"xcode-select --install"
next you can run
"gem install rails -v 4.2.4"

Gravatar

Also for me.

Gravatar
Talal Alobaid on

Both brew and brew cask are working fine for me.

Gravatar
Nenad Novakovic on

If it had any problems before, it does not have any problems now.
Homebrew is brewing fine with El Capitan!

Gravatar
Debjit Saha on

Agree!

Gravatar
Debjit Saha on

Yes, the issues were due to OS X El Capitan's new feature called System Integrity Protector. I have outlined a quick and easy fix here - http://digitizor.com/2015/1...

Gravatar

I don't see any issues with homebrew, brew install // brew cask install etc and El Capitan

Gravatar

Indeed it works fine now, but not 4 month ago.
You have to fix permissions to /usr/local, update brew and
do xcode-select in case of upgrading OSX though!

Gravatar

On my mac, you are right


Gravatar

Thanks. This worked great. The one thing I did find is that after installing mysql I rebooted as I could not invoke mysql at the command line. Other than that works great! Thanks!


Gravatar

Awesome post :)
Looks like really clean installation.


Gravatar

I failed at rbenv install 2.2.0:

BUILD FAILED (OS X 10.11 using ruby-build 20150719)


Gravatar
Kameron A Robinson on

I had a problem installing rails got back "extconf failed, exit code 1"


Gravatar
antonioreyna on

hello, when i do ruby -v i get 2.0.0 but when i do rbenv version i get 2.2.3 is that ok?

Gravatar
Антон Машошин on

it seems that you already tryed to install ruby via brew... try "brew uninstall ruby". i had the same problem, after that i got right ruby version


Gravatar
Alejandro Ventura on

Cool it works for me now!
What do I need to do to change the password if the user is my computers username? And how to turn it on/off when I want to?

Gravatar

Did u disabled SIP on OSX El Capitan?

Gravatar
Alejandro Ventura on

No! I don't I just run the commands written in the blog and thats it


Gravatar
Alejandro Ventura on

Is there a PrefPane for Postgresql in Mac OS like the Mysql one? I don't want the server runs at start up

Gravatar

Instead of homebrew you could use http://postgresapp.com/ which only runs when you launch the app.

Gravatar
Alejandro Ventura on

But I have read that Ruby on Rails don't work fine because of the "c" libraries that postgresql need to communicate with the gem. Those libraries are not installed using the app, you need to run the installer in order to install those libraries in the shell.
What about that?

Gravatar

Works fine here with rails 4 and the pg gem. Just follow the documentation.

Gravatar
Alejandro Ventura on

Alright I will check! Thanks for your support!

Gravatar

I've had a quick look at the docs and think this is the page you need.
http://postgresapp.com/docu...

Basically you need to add the .app to your $PATH (as the docs show in a page it links to). That's the only setup I remember doing here. The nice thing about this method is you don't have to do any arcane account setup to get something working (for local development). pg_restore and similar also become available in the terminal, since they're now on your path.

Just remember not to use sudo to install the gem (as that page suggests) because it'll mess with the permissions in your rbenv install, which should be in your user account & not need sudo (fixable with something like sudo chown -R $(whoami) ~/.rbenv)

Gravatar
Alejandro Ventura on

Thanks brother!


Gravatar

i am facing a problem while installing Rail (gem install rails -v 4.2.4)

its shows an error like while executing gem ... (Errno::EACCES)

Permission denied - /Library/Ruby/Gems/2.0.0/gems/nokogiri-1.6.6.2/.autotest

in the terminal
any one suggest me a solution

Gravatar
Drew Garcia on

I don't know the benefit to using rbenv vs rvm but I uninstalled Rbenv, bc I was having similar issues. Installed RVM and everything is working.

Gravatar

It looks like either rbenv isn't installed properly, e.g. missing from your .profile or .bashrc or whatever, or it's installed but you haven't told it to use a ruby version other than your system ruby (which would install to /Library/Ruby and require sudo permissions). Install another ruby with the rbenv ruby-build plugin (also available through homebrew) and use rbenv local to switch a particular project directory to use that ruby version (it creates a .ruby-version file in the directory).


Gravatar

I'm having difficulties on El Capitan. I'm following the instructions here. But I'm stuck on the last step here.

The command "rails server", is returning an error.

"Could not find pg-0.18.3 in any of the sources

Run `bundle install` to install missing gems."

I have ran "bundle install" and when I try to run "rails server", I get the same error again.


Gravatar

Worked perfectly for me on El Capitan 10.11.

Gravatar
Peter Peťuldo Mihok on

I always get this error message, when I open this local host web page:
Specified 'mysql2' for database adapter, but the gem is not loaded. Add `gem 'mysql2'` to your Gemfile (and ensure its version is at the minimum required by ActiveRecord).

Gravatar

Peter, you need to open yourapp/Gemfile with any texteditor or ide you like, and add string: gem 'mysql2' to your Gemfile, it's easy.

Gravatar
Peter Peťuldo Mihok on

It's written there, but still not working.

Gravatar

Use the "bundle install" command in your app folder to run the Gems installation ;)

Gravatar
Peter Peťuldo Mihok on

Ok, here's my problem. After finishing this whole installation and after all these advices you gave me here I want to run my rails server command. After this command I click here on this localhost:3000 and it says the same error as I mentioned up there....So Idk if it's just the error of the localhost, or I did mistake somewhere else.

But thanks guys for helping me...I'm really frustrated with just installing this ruby and it really keeps me away from wanted to learn this, cause it's not running as it should.

Gravatar

You now have to give Rails informations about you database in your database.yml file.
I suggest you to watch the "How to deploy Ruby on Rails" video, you'll learn valuable things about all of this!

Anyway, in the database.yml, you can tell Rails where to find your database and how to access it.
Pay attention you can run in few environments, so you have to specify default informations, or informations for each environment.
It will look like this :

development:
adapter: mysql2
encoding: utf8
database: my_db_name
username: root
password: my_password
host: 127.0.0.1
port: 3306

Gravatar
Peter Peťuldo Mihok on

Thanks mate. OK I tried to reinstall whole ruby on rails and I also got the same error. Everything went OK untill I had to write rake db:create after this command I've got this error message:

Gem::LoadError: Specified 'mysql2' for database adapter, but the gem is not loaded. Add `gem 'mysql2'` to your Gemfile (and ensure its version is at the minimum required by ActiveRecord).

Gem::LoadError: can't activate mysql2 (~> 0.3.13), already activated mysql2-0.4.2. Make sure all dependencies are added to Gemfile.

I looked to my Gemfile and there's written gem 'mysql2', so I don't know where the problem is.

Srozen maybe, if you can give me your e-mail/skype/FB and we can talk about it in details, it'd help me a lot.

Gravatar

It's a known bug, change the following in your Gemfile

gem 'mysql2'

to

gem 'mysql2', '~> 0.3.10'

and then use "bundle install" in command prompt

Gravatar
bog_weasel on

Was your mysql server running? I get the same error if I don't run 'mysql.server start' before 'rails server'.


Gravatar

The only thing that worries me is that I have to use "sudo" for the installation. I'm hoping this is understood, and not included for clarity.

Gravatar

You shouldn't ever have to use sudo for this. If you do, you're going to end up with permissions errors later on. Homebrew might in order to change permissions for some of its own folders where you install apps from, but the rest of it shouldn't ever use sudo.


Gravatar
Kenny Mann on

If you have XCode installed then run this BEFORE you try to install rails (or you'll keep running into errors):
xcode-select --install

I took this from: http://stackoverflow.com/qu...

I forgot to add what's going on. You need the command line tools and that's what this installs.


Gravatar

I ran the rails app and it doesn't seem to have any errors but when I go to the "localhost:3000" site, it tells me that, "This webpage is not available." Is there any other way to see if the database actually ran? Thanks.


Gravatar

I upgraded to El Capitan with homebrew already installed. I found that I had to remove the old version of homebrew and then reinstall it, run brew doctor (correct any errors) and then I was good to go!


Gravatar

I tried doing this a few weeks ago and ended up messing up the bash file. Fast forward to know, when I go to do the first step the first thing I get is:

"-bash: l: command not found"

can I reset the "bash"? I am quite new to this and not sure how to properly use the terminal.
Thanks in advance for any advice


Gravatar

Hello.

When visit localhost:3000

I'm greeted with error: Specified 'mysql2' for database adapter, but the gem is not loaded. Add `gem 'mysql2'` to your Gemfile (and ensure its version is at the minimum required by ActiveRecord).

I'm a new user, and not sure how to proceed.

Gravatar

Was able to find a fix via http://stackoverflow.com/qu...

SOLUTION:
It's currently an issue with Rails 4.1.x and 4.2.x, per this bug report, it will be fixed in the next release of rails 4.2.x (credit to dcorr in comments for the link).
In the mean time you can fix by doing downgraded to version 0.3.18 of mysql2 by adding this line to your gemfile:

gem 'mysql2', '~> 0.3.18'


Gravatar

I'm having an issue with
# Load rbenv automatically by adding

# the following to your profile:

eval "$(rbenv init -)"

popping up every time I open up iTerm/Terminal


Gravatar
Rinaldo Bonazzo on

Thanks a lot for your help


Gravatar
nissandookeran on

There's a bug I encountered when following the instructions for setting up with mysql. Wrote the fix steps at http://blog.redditech.com/p... (really just need to update RubyGems and then run 'gem update' to upgrade to rails 2.4.5, which I think fixes the issue)


Gravatar
raulsergioUS on

This link https://gist.github.com/vpa... helps me a lot with El Capitan


Gravatar
James Jackson on

Same here, worked like a dream on El Capitan v10.11.1


Gravatar
Tomo Okabe on

thank you! was really helpful.
the only part that i had a difficulty was that when installing rails, the terminal stopped for a bit so i thought it was causing some problems... :( But worked perfectly and it was so easy to get everything sorted! Thank you so much


Gravatar
João Reis on

Thanks for the good instructions. I would recommend to install postgres from the Postgres.app for mac: http://postgresapp.com/ and get pgAdmin3 app for mac for querys and stuff: http://www.pgadmin.org/down...


Gravatar

I have created a video based on this guide at:
https://www.youtube.com/wat...


Gravatar
suq_madiq on

Awesome documentation! Thanks!


Gravatar

why isn't there rvm installation guide?


Gravatar

I keep getting the following error...

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

...when trying to run the code to add rbenv to bash. Help please!!

I may have installed newer versions of ruby first before running this code. Not sure if that would complicate things.

Gravatar

Did you get this fixed? i too am getting this error

Gravatar

Your ~/.bash_profile should just have one line that is that same as what's in the single quotes on that first line.

if which rbenv > /dev/null; then eval "$(rbenv init -)"

Looks like he had accidentally combined those two commands to run on accident.

Gravatar

Hi Chris,
Could we get the page updated to be a bit clearer?

I'm still not 100% what I need to do in that step. Or should I just edit the .bash_profile file?

Gravatar

You should just copy and paste each line into your terminal and run each one. Make sure that your copy/paste didn't mess up the command during the paste. I'm not sure what's causing you guys to get malformed commands.

Gravatar

I'm
Not sure mate, that's all I did. Copied the first line. Pasted. Hit enter.
Then copied the second line. Pasted that. Hit enter again. It's this bit that brings up the error

I saw on stack overflow someone mentioned a ; after the fi

Gravatar

If your error was like his, it is showing that the "source" line also got copied into the file, so the ending single quote didn't get applied right most likely to close the string. Not having an ending semicolon is fine (just tested it again). Sometimes when pasting stuff into terminal there are weird things that cut off lines short or your browser can mess with quotes and make them curly when they should be straight (http://practicaltypography.... That shouldn't happen in a code block though. I can't reproduce the issue you guys are having with Chrome and both iTerm and Terminal so not entirely sure what's wrong for you guys, but it's one of these things.

Gravatar

@excid3:disqus i opened up my .bash_profile and it had that line multiple times I removed them and I added the one you mentioned above and i get an error - -bash: .bash_profile: line 2: syntax error: unexpected end of file

Gravatar

If you haven't fixed your error, is the problem. When you first followed the installation steps, you most likely copied the two lines of code incorrectly. However, now the incorrect code is save in your .bash_profile. Every time you open your terminal it's calling the .bash_profile and generating an error. Your error says that line 2 has a syntax error. To fix it, you need to open the .bash_profile file delete the incorrect code.

Follow these steps on how to edit the bash profile. https://natelandau.com/my-m.... Only remove the lines of code pertaining to this install. Save it, close it, and run the two lines of code again (you could just type it in also).

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

Hope that helps.

Gravatar

Hey Jesica :) thanks. I found these instructions worked a litter easier

Enter the following in your terminal window

$ touch ~/.bash_profile; open ~/.bash_profile

In the text editor window that opens add the following code:
if
which rbenv > /dev/null; then eval "$(rbenv init -)"
fi

Saved your .bash_profile


Gravatar
Ningchuan Li on

# To have launchd start mysql at login:

ln -sfv /usr/local/opt/mysql/*plist ~/Library/LaunchAgents

I think current is
ln -sfv /usr/local/opt/mysql/*.plist ~/Library/LaunchAgents


Gravatar

Please help me if you had same problem like this. I have a problem with this code "ssh -T [email protected]". When I put this line of code I received this:

Gravatar

that's because you're in the wrong folder and github doesn't find the publickey, so what you need to do is find the right path, then try again and it will works, at least for me, that was the solution.


Gravatar

Works great! :)


Gravatar
YiLong Liu on

Hello guys I hope you are having a good day, I'm accessing to Localhost:3000 , It seems everything is installed correctly, but after I run rails server and copy and paste the url the following message is displayed: We're sorry, but something went wrong(500), do you know what is the reason of this?


Gravatar
Saurabh Agrawal on

How to install rails gem without docs? Also how to make that default?


Gravatar

How do you install in China?

ERROR: While executing gem ... (Gem::RemoteFetcher::FetchError)

too many connection resets (https://rubygems.global.ssl...

Keep getting this


Gravatar
The Marionettist on

Thanks! Cheers!

Great set-up guidance here for a rapid deployment... took less than 30 for me; by about 2 minutes.


Gravatar
Moritz von Haacke on

Great tutorial


Gravatar
Kaan L Caglar on

Works like a charm! Thanks.


Gravatar
John Habibi on

Great walk through! I had to side step over to github to makes sense of establishing a new SSH key, but overall A+++


Gravatar

Awesome guide, worked like a charm on El Capitan and getting Postgre setup straightaway rather than having that oh S*** moment as I try to deploy to heroku next time was a good finishing touch. Thanks.


Gravatar
Alejandro Pelaez on

Muchas gracias. Funcionó muy bien en El Capitan 10.11


Gravatar
Shannon Moon on

Rails install failed for me on a new install of el capitan (10.11.6) with this error: libiconv is missing. please visit http://nokogiri.org/tutoria... for help with installing dependencies. I installed nokogiri with gem install nokogiri and then was able to successfully install rails and proceed with the installation.


Gravatar

Thks for the tutorial but when el open the terminal, it display this

Last login: Sun Aug 7 21:52:21 on ttys000
-bash: /Users/MacBookPro/.bash_profile: line 3: syntax error near unexpected token `source'
-bash: /Users/MacBookPro/.bash_profile: line 3: `if which rbenv > /dev/null; then eval "$(rbenv init -)"; fi source /Users/MacBookPro/.bash_profile'
MacBook-Pro-de-MacBook:~ MacBookPro$

how can I revert or fix it?

regards


Gravatar
Nadeem Jabbar Qureshi on

In El Capitan, you might also need to do `sudo gem install bundler -n /usr/local/bin´.

Please see: https://github.com/bundler/...


Gravatar

I received the error detailed in the last part of the tutorial, but am unclear on how to update the config/database.yml file


Gravatar
Uladzislau on

Hey hey! Some tips:
PLEASE, ADD this IN ARTICLE.

Configuring Git section.
after generating ssh-key you need to do:
eval "$(ssh-agent -s)"
ssh-add ~/.ssh/id_rsa
check this by ssh-add -l

and the following text after cat ~/.ssh/id_rsa.pub
add it to your ssh-key in GitHub account.

cause I were bound by Permission denied problem without this actions


Gravatar

Still working on OSX 10.11 El Capitan! Tnx!


Gravatar

So, for me 'gem install rails -v 4.2.6' yielded the error 'ERROR: Error installing rails: ERROR: Failed to build gem native extension.' What fixed it was installing xcode commadline tools with 'xcode-select --install'. Maybe you can add this information to the post or open a troubleshoot section.


Gravatar
Evert Smit on

Can anybody help me as i want to install Homebrew and ruby on rails on my Macbook OSX 10.8.5 2 months back i still could install homebrew but now it gives the following error.

Last login: Sat Oct 29 15:02:30 on ttys000

mrrobotas-MacBook-Pro:~ mrrobota$ /usr/bin/ruby -e "$(curl -fsSL https://raw.githubusercontent...."

curl: (22) The requested URL returned error: 404

mrrobotas-MacBook-Pro:~ mrrobota$


Gravatar

Unable to install rails - getting the following error: ERROR: Error installing rails:
activesupport requires Ruby version >= 2.2.2.
New to this stuff, has anyone had the same issue?

Gravatar

Hi Nat! did you solve this issue? seems that version 2.4.0 was installed in ~/.rbenv, and when i call `ruby -v`, it references an installation in /usr/bin/ruby


Gravatar

Thank you so much.


Gravatar
hannah lee on

Thanks a lot. It worked fine :D


Gravatar
Mounika Smitha on

Best tutorial for beginners.


Gravatar
Mounika Smitha on

Best tutorial for beginners!


Gravatar

Thumbs up.It worked perfectly


Gravatar
Anto Boalis on

all steps followed till the creation of SSH key. I put your command into Terminal, but nothing happens:

cat ~/.ssh/id_rsa.pub


Login or create an account to join the conversation.