After following many outdated and incomplete instructions for setting up a web development environment on a Mac (back in Spring 2011), and spending a lot of time finding solutions to the problems I encountered along the way, I decided to put together this detailed tutorial.

As of July 21st, 2017 this guide is deprecated.

Note: Updated on May 16th, 2015.

It’s best that you start with a clean installation of OS X. If you’ve already tried to install a development environment, I can’t guarantee that you won’t run into any issues. Certain tools used in this tutorial might not be compatible with whatever you might have installed. For example, RVM is not compatible with rbenv, and MacPorts is not compatible with Homebrew.

The easy way for Yosemite:

Step 1: Download and Install the Command Line Tools

Installing the standalone Command Line Tools on Yosemite

Most of the work you’ll be doing in this tutorial will be in the “Terminal” application. The easiest way to open an application in OS X is to search for it via Spotlight. The default keyboard shortcut for invoking Spotlight is command-Space. Once Spotlight is up, just start typing the first few letters of the app you are looking for, and once it appears, select it, and press return to launch it.

Inside the Terminal window, copy and paste (or type) the following command, and press the return key on your keyboard:

xcode-select --install

You should see the pop up below on your screen. Click Install when it appears.

Click Agree when the License Agreement appears:

Your computer will then attempt to find the software, and then will start downloading it.

Once the software is installed, click Done. That’s it! You’re now ready to go to Step 2.

Step 2: Install Homebrew

Homebrew, “the missing package manager for OS X,” allows you to easily install hundreds of open-source tools. The full instructions are available on the Homebrew Wiki, but you should only need to run the command that’s listed at the top of the Homebrew site:

Update: Even better just head over the official Homebrew site and get the link from there.

ruby -e "$(curl -fsSL"

Note that the command listed on the Homebrew site could change, so please make sure that what I have listed above is the same. If it isn’t, please let me know and I’ll update it.

Copy and paste the command into your Terminal window, press return, then follow the instructions when prompted. Note that Terminal does not provide visual feedback when you type your password. Just type it slowly and press return.

Once the installation is successful, run the following command:

brew doctor

If you get Your system is ready to brew, you can move on to Step 3.

Step 3: Install Git

Git is the version control system of choice among many web developers. With Homebrew, installing Git is as easy as this:

brew update brew install git

Since we just installed Homebrew, we could have skipped brew update, but it’s a good habit to run it before installing anything with Homebrew because Homebrew is updated regularly.

To verify:

git --version

You should get git version 2.3.3 or later.

Run brew doctor to make sure everything is still working. If your system is ready to brew, you can move on to Step 4.

Step 4: Configure Git with GitHub for Mac

Download, install, and launch GitHub for Mac.

If you don’t have a GitHub account, click on the Sign Up at link in the app, then come back to the app to complete the setup. I highly recommend that you turn on two-factor authentication for your GitHub account.

Follow these steps to set up GitHub for Mac when you first launch it:

  • Click Continue
  • Enter your username and password, then click Sign In
  • Enter your two-factor authentication code (if you have it turned on)
  • Click Continue
  • Enter an email address that you want to be attached to your commits. It doesn’t have to be your real email address, but if you leave this blank, Git will nag you about it every time you commit.
  • Click Continue
  • Click Done

Option Two: Best Way To Manually Configure Git

Like any other software you’ll need to configure git in a way that it will best suit you for your development needs:

git config -l

Let’s now configure the global user:

git config --global "Your Name Here"

Now let’s set your global e-mail:

git config --global "Enter Your E-mail Here"

Let’s set one more option:

git config --global color.ui true

This will set different colors in files when viewed via terminal.


If you’re going to be using GitHub to push out code let’s go ahead and create an SSH key:

ssh-keygen -t rsa -C "Enter Your E-mail Here"

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

You should get a message like this:

Hi [Your Username]! You've successfully authenticated, but GitHub does not provide shell access.

To view all set options just type the following command:

git config --global -l

Note: Make sure to keep your git version updated all the time, this guide will show you how to accomplish this.

Step 5: Install RVM with the latest Ruby and Rails

Update: There is a better way to install Ruby and all the gems that come with it, this is my preferred method. Both RVM and rbenv will work it’s up to you which method you would want to deploy.

RVM stands for Ruby Version Manager, and is one of the most popular tools that allow you to install and manage multiple versions of Ruby and Rails on the same computer.

RVM has come a long way. As of March 30, 2013, you can now install the latest RVM, Ruby, and Rails in one step. However, because RVM installs documentation for every gem that Rails depends on, which takes forever, I recommend disabling documentation first:

echo "gem: --no-document" >> ~/.gemrc

Now you can install everything with one command. If you’re not interested in Rails, just replace –rails with –ruby in the command below:

curl -L | bash -s stable --auto-dotfiles --autolibs=enable --rails

Read the RVM installation documentation to see all the different options you can use.

This will take a few minutes, and once it’s done, quit and relaunch Terminal, then run this command:

type rvm | head -1

If you get rvm is a function, that means RVM was successfully installed.

To make sure the latest versions of RVM, Ruby and Rails were installed, run the commands below:


rvm --v

You should get rvm 1.26.10 or higher.

For Ruby

ruby --v

You should get ruby 2.2.1 or higher. If you get dyld: Library not loaded: /usr/local/lib/libgmp.10.dylib, that means something is wrong with the binary version of the latest Ruby. To fix it, reinstall your desired Ruby version by disabling the binary:

rvm reinstall 2.2.1 --disable-binary

For Rails

rails --v

You should get Rails 4.2.0 or higher.

To make sure your system is still ready to brew:

brew doctor

If everything went well, you’re done! Your machine is now set up with the basic tools for web development.

Next Steps

Once you start hacking away on your computer, you will most likely need to install more tools with Homebrew. Before you do, remember to always run brew update and brew doctor to make sure your system is still ready to brew. To upgrade your existing packages, run brew upgrade.

If you installed the full Xcode package, remember that when you update it via the Mac App Store, you might also need to update the Command Line Tools via Xcode’s Preferences. If you installed the standalone CLT, I recommend checking for a new version once a month or so.

If the above five steps seem too much work for you, then you should consider another career! But here’s an amazing script from Moncef Belyamani that can automate the whole setup for you: Laptop Script. Cheers!