Setting Up Your Ruby Environment on a Mac


In this post I’m going to explain how to install Ruby on macOS using the Ruby version management tool rbenv. You might ask why we need to install Ruby in the first place when Ruby comes already pre-installed on your system by default. The reasons are:

  • The system-provided version of Ruby is outdated.
  • With that pre-installed version it’s not possible to install gems (more on gems later), since the directory where they would be installed into is now protected by System Integrity Protection.1

Installing Homebrew

First, you need to install Homebrew in case you haven’t already. I covered Homebrew in-depth in a previous blog post. It would be really helpful if you read it first.

Installing Ruby

For beginners, installing the latest version of Ruby via Homebrew is perfectly fine:

brew install ruby

Advanced users, however, want to have a little bit more control over which version they install, for example because their different projects each require a very specific version of Ruby and they need to switch between those versions as they work on their various projects. There are tools made for exactly this purpose. One of them is called rbenv. If you want to use rbenv, you also need to install ruby-build.

brew install rbenv ruby-build

After you have installed rbenv, you still need to add a line of code to a specific file before you can use rbenv. Depending on your machine’s configuration, that file could be either ~/.bash_profile or ~/.profile. If you don’t know what these files are, read my post about these so-called dotfiles. I configured my system to use ~/.profile. So you shouldn’t just blindly copy & paste the following code, since it wouldn’t work on your machine if you configured it differently than I configured mine. So you should really read that linked article to understand which file you need to use:

echo 'if which rbenv > /dev/null; then eval "$(rbenv init -)"; fi' >> ~/.profile # adds the quoted code to the file ~/.profile
source ~/.profile # reloads that file to make the change effective

Now that rbenv is working, you can use it to install Ruby if the simpler approach didn’t fit your needs. First, check out the Ruby Downloads page to see which version is the latest. At the time of this writing it was version 2.3.2. With that information, execute the next two commands with that version number as parameter:

rbenv install -v 2.3.2
rbenv global 2.3.2

The first command is self-explanatory. The second command defines which Ruby version a shell (terminal) should use in case no specific version was stated, i.e. the fallback version.

At this point, you should have the latest version of Ruby installed. Verify that Ruby was installed properly with this command:

ruby -v

Alongside with Ruby, its package manager RubyGems (similar to pip in Python) was also installed. You can verify this like so:

gem -v

With this package manager, you can now install programs written in Ruby, so-called gems. For example, you could install Jekyll to build your own blog, just like this one. You would install Jekyll like so: gem install jekyll.

For each gem that you install, RubyGems will generate local documentation. It is likely that do not want this, since this process can take quite a long time. To disable this behavior, run the following command:

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

Installing Bundler

We’ve just seen how to install a gem. But if you need to install not just a single gem but many, as it is common, it would be quite tedious to install each gem individually. Furthermore, this would install gems globally, i.e. system-wide. According to the best practices for building Twelve Factor apps, apps should not rely on the existence of system-wide packages. On your specific machine, everything could work perfectly, but if you shared your application with someone else it would break on their machine. For that reason, it is common in the Ruby world that developers include two files when you download their application: the so-called Gemfile and a file called Gemfile.lock. The Gemfile contains all the requirements of the app, i.e. all the gems you need to install. The file Gemfile.lock contains the corresponding version number of these requirements, i.e. the version numbers the developer has used to test his application and is sure that his application will work on your machine if you use exactly these version numbers.

So that you don’t have to install each gem individually, there is a tool called Bundler which installs all stated dependencies in their specified version number. You first need to install Bundler:

gem install bundler

Because Bundler provides new commands, you then need to run the following command in case you followed the advanced approach and installed Ruby via rbenv. This is necessary every time you install a new version of Ruby or a gem that provides new commands, such as Bundler:

rbenv rehash

This command installs the shims for all Ruby executables managed by rbenv. A rbenv shim intercepts a Ruby-related command and calls rbenv exec which then takes care of running the right executable. So basically this command allows us to use the new gem. Again, this command is necessary only if you followed the advanced approach and installed Ruby via rbenv.

Now that you have Bundler installed, you can simply cd into a directory after you e.g. cloned it from GitHub and perform bundle install. This will install all the requirements listed in the Gemfile. You can also run bundle update. This will update all the installed gems to their latest version, however without the garantee that the downloaded application will still work afterwards.

  1. A security feature introduced with macOS El Capitan.