Installing Ruby the Correct Way

Published 2013-03-27

Ruby is an extremely flexible, concise language which boasts a rampant proliferation of libraries and popular frameworks like rails. However, using your system's default ruby to install gems is a quick path into dependency nightmares, as different gems fight to use different versions of the same library.

I'll walk you through how to avoid this using rbenv, ruby-build, and bundler. At the conclusion, you'll have a better understanding of where ruby lives on your system and you'll also have a stable, flexible ruby installation that can grow with new development while simultaneously providing a bulletproof runtime environment for existing applications and tools.

Questions Before we Begin

What about RVM?

RVM is another tool that purports to alleviate ruby's dependency issues. Having used both rvm and rbenv on OSX, CentOS, and Ubuntu, I find rbenv to be simpler and more reliable.

I already have some ruby stuff installed. What do I do?

Skip to the "Resetting Your Ruby Installation" appendix at the end of this article. Once you're done, return here and proceed onward, to glory!


In order to install rbenv and ruby-build you'll need git and a c compiler. On *nix you can usually get the c toolchain via the build-essential package. On Mac, the c compiler comes from Xcode or the CLI tools for Xcode, which is a much smaller download.

Install rbenv

rbenv or "ruby environment" is a CLI tool that enables you to quickly and easily switch between different rubies installed on your system. We're also going to install ruby-build at the same time.

Ubuntu note: Use ~/.profile instead of ~/.bash_profile below. Also, we'll need to install some dependencies first:

$ sudo apt-get install -y libssl-dev zlib1g-dev libreadline-dev

On to the rest!

$ git clone git:// ~/.rbenv
$ git clone git:// ~/.rbenv/plugins/ruby-build
$ echo 'export PATH="$HOME/.rbenv/bin:$PATH"' >> ~/.bash_profile
$ echo 'eval "$(rbenv init -)"' >> ~/.bash_profile
$ exec $SHELL -l

rbenv and ruby-build are now installed. If you'd like to learn more about rbenv or ruby-build, refer to @sstephenson's docs -- they're top-notch.

Note I previously recommended adding RUBY_CFLAGS="-march=native -O3" to your .bash_profile to make ruby faster, but this caused some issues in later versions of ruby so if you have it there now, take it out.

Installing a ruby

Once rbenv and ruby-build are installed you can install a ruby:

$ rbenv install --list

To see a full list of available rubies, or for popular rubies (at the time of writing):

$ rbenv install 1.9.3-p392
$ rbenv install 2.0.0-p0

This will download the source, compile, and install ruby, which will take a few minutes depending on your internet connection and CPU.

When you're done installing rubies, run:

$ rbenv rehash

Switching between rubies

Once at least one ruby is installed, you'll want to set it as the global default so you have a ruby available for doing fun ruby things:

$ rbenv global 1.9.3-p392
$ ruby -v
ruby 1.9.3p392 (2013-02-22 revision 39386) [x86_64-linux]

$ rbenv global 2.0.0-p0
$ ruby -v
ruby 2.0.0p0 (2013-02-24 revision 39474) [x86_64-linux]

If one of your projects requires a specific version of ruby, you can specify this by running rbenv local VERSION inside the project directory. This will drop a .ruby-version file into your project, which you can check into source control. That way the version constraint is shared with your team.

You may have noticed that which ruby doesn't really work anymore since it just points to the rbenv shim. If at any point you're not sure which ruby you're using, type rbenv version to see.

Configure Gem

Create ~/.gemrc with the following contents:

install: --no-ri --no-rdoc
update:  --no-ri --no-rdoc

This will prevent gem from installing local documentation for each gem it installs which, honestly, you aren't going to read anyway. This makes gem install run much more quickly and use less space.

Recap So Far

We've installed rbenv, compiled a version of ruby using ruby-build, and set our default ruby. We have rbenv installed under ~/.rbenv/ and rubies under ~/.rbenv/versions/. We added a .gemrc to keep our gems lean.

Install bundler

Now that we have ruby, we'll want to install some gems. After all, managing gems is the whole reason we embarked on this journey. Fortunately, ruby-build already installed gem for us. Now we need bundler.

bundler is a tool that allows you to install multiple gem versions side-by-side, and sandboxes each project so that its gem dependencies don't conflict with other projects. Additionally, bundler allows you to deterministically re-install all of your project depenencies on other developer machines, on production, etc.

$ gem install bundler
$ rbenv rehash

We need to run rbenv rehash any time we install (or remove) an executable like rake, bundle, etc. or a new ruby version. This makes rbenv rebuild all of the shims used to launch those executables.

Now hop into your project and type:

$ bundle install

bundler will examine your Gemfile and install all of the listed dependencies.

Note: You'll need to perform gem install bundler for each version of ruby you install.

Using bundle exec

The tricky bit with bundler is that we've probably installed several versions of a gem. Which one do we use, and how do we locate it on the PATH? We don't. bundler does this for us.

Rather than running rake from the terminal, we'll run:

$ bundle exec rake

This ensures that the version of rake that's tied to our application is the one that gets executed, even if we have 5 versions on our system. If you're not in a project context (i.e. there's no Gemfile in your directory), feel free to call rake from the terminal.

If you're only consuming apps and libs it should be sufficient to run bundle install and bundle exec, but if you're writing ruby code you'll probably find the bundler docs very useful.


From now on, just remember to run bundle exec rake instead of rake and you'll be completely sandboxed. You'll never have a project stop working because you installed another version of a gem somewhere else.

Since typing bundle exec is somewhat verbose, you can create an alias like be or bex or similar to make life easier.

$ alias bex="bundle exec"
$ bex rake

You can add this to your ~/.bash_profile or similar to make it persistent.

Appendix A: Resetting Your Ruby Installation

"Help! I have a (messed up) ruby installation already!"

The following steps will help you remove rogue rubies from your system. This is potentially destructive. You have been warned.

Check whether rvm is in your path, and if so, remove it from your path and delete rvm using implode.

$ echo $PATH | grep rvm
$ rvm implode

If you prefer, you can move ~/.rvm somewhere else to back it up, or rm -rf ~/.rvm. Restart your terminal after this is done.

Check whether you have more than one ruby installed:

$ which -a ruby

If you're on Mac, remove all rubies except system ruby, which installed at /usr/bin/ruby. System ruby ships with OS X and removing it will cause Bad Things to happen. If you're on linux, you can safely remove all rubies using your package manager, or rm if you installed them some other way.

If system ruby is still there when you're done, uninstall all gems from system ruby:

yes | sudo gem uninstall -a --ignore-dependencies `gem list --no-versions`

Restart your terminal so everything is flushed. At this point, you should be able to type:

$ which ruby
$ which gem
$ gem list --local

And see /usr/bin/ruby and /usr/bin/gem on Mac, or nothing on Linux.


ruby bundler rbenv ruby-build