Up and Running with rbenv

Ian Oxley
Ian Oxley

rbenv is a tool that lets you install and run multiple versions of Ruby side-by-side. It’s a simple, lightweight alternative to RVM that focuses solely on managing multiple Ruby environments.

Each version of Ruby is installed in the ~/.rbenv/versions directory. It uses shims to switch between versions and these are located in the ~/.rbenv/shims. The job of the shims is to grab the directory for your desired version of Ruby and stick it at the beginning of your $PATH and then execute the corresponding binaries.

rbenv requires you to install each version of Ruby in the ~/.rbenv/versions directory. It uses shims to switch between versions and these are located in the ~/.rbenv/shims. The job of the shims is to grab the directory for your desired version of Ruby and stick it at the beginning of your $PATH and then execute the corresponding binaries.

Both rbenv and RVM do a good job of managing multiple Ruby environments. In a moment we’re going to have a look at installing rbenv and setting up a few Ruby versions. Before that, lets look at some other factors you might want to take into account when deciding whether to go with rbenv or RVM.

Why might I use RVM?

Like rbenv, RVM lets you install and run multiple Ruby environments side-by-side. But it also provides:

  • built in support for installing Rubies e.g. rvm install 1.9.2; with rbenv you have to build Rubies manually yourself
  • a flexible gem management system called Named Gem Sets which eases management of gems across multiple environments
  • the ability to have identical, self-contained environments e.g. development, CI, staging and production
  • the ability to test against multiple Ruby versions simultaneously e.g. when upgrading 1.8.x to 1.9.x, JRuby, etc.

Why might I choose rbenv?

rbenv is built in the UNIX tradition of doing one thing and doing it well. It’s sole focus is on managing multiple Ruby environments and providing simple means to do just that:

  • You can choose which version of Ruby to use on a global and per-project level.
  • It’s also possible to override these settings with an environment variable.

In contrast to RVM, rbenv doesn’t:

  • override any built-in shell commands
  • come with any way of managing gems (the recommended way is to use Bundler or rbenv-gemset)
  • come with any mechanism to install versions of Ruby

ruby-build can be integrated wit rbenv to ease installation of Ruby versions. The alternative is to download and build each version of Ruby yourself, which is what we’re going to do in the rest of this article.

Lets have a look at installing rbenv and setting up a few Ruby environments.


NB rbenv is not compatible with RVM. If you’ve already got RVM installed you’ll need to remove all references to it before trying rbenv. If you don’t then rbenv may appear to work but will come unstuck when you try to install a gem. According to the rbenv README this is because RVM overrides the gem command with a shell function.

rbenv currently lives at https://github.com/sstephenson/rbenv. The README file contains the steps we need to follow to install it on our system. If you’re on OS X you could go for the easier option and install rbenv via Homebrew. But we’re going to have a look at how you can download the source code and build it yourself.

A few quick notes before we start:

  • I’m installing this on Ubuntu. If you’re following this on OS X you’ll need to replace all references to .bashrc below with .bash_profile
  • On OS X you’ll need to have Xcode installed to be able to compile the source code. You an find Xcode on your OS X installation DVD or download it from http://developer.apple.com/technologies/tools/
  • As we’re grabbing the source code off GitHub it’d be useful if you had git installed :)

Let’s begin:

  1. Open up the terminal and make sure you’re in your home directory before cloning the GitHub repository into ~/.rbenv:

    $ cd
    $ git clone git://github.com/sstephenson/rbenv.git .rbenv
  2. So that we can access rbenv on the command line we’ll need to add it to our $PATH:

    $ echo 'export PATH="$HOME/.rbenv/bin:$PATH"' >> ~/.bashrc
  3. We then need to add rbenv init to our shell to enable shims and autocompletion. If we restart our shell we’ll be up-and-running straight away:

    $ echo 'eval "$(rbenv init -)"' >> ~/.bashrc
  4. If we restart our shell we’ll have rbenv and autocompletion available straight away:

    $ exec $SHELL
  5. To keep things tidy you might want to create a folder in your $HOME directory to keep each Ruby version’s source code in:

    $ cd
    $ mkdir rubysrc
  6. Next download the latest version of the Ruby source code:

    $ curl -O http://ftp.ruby-lang.org/pub/ruby/1.9/ruby-1.9.2-p290.tar.gz
  7. Unpack the download then cd into the newly extracted folder:

    $ tar xzvf ruby-1.9.2-p290.tar.gz
    $ cd ruby-1.9.2-p290
  8. Then run configure, make and make install making sure you’ve entered the correct version number in the ./configure --prefix path:

    $ ./configure --prefix=$HOME/.rbenv/versions/1.9.2-p290
    $ make
    $ make install

    You should now find you’ve installed Ruby 1.9.2 in the ~/.rbenv/versions/1.9.2-p290 folder

  9. The final step is to run rbend rehash so the shim binaries get rebuilt. It’s recommended to do this anytime you install a new Ruby binary, be that a new version of Ruby itself or a gem that comes with a binary.

Installing Another Version of Ruby

Ok, so we’ve got the latest version of Ruby installed. Now lets download and install the release candidate and then have a look at how we can switch between the two versions with rbenv:

  1. Download the release candidate code from (http://www.ruby-lang.org/):

    $ cd ~/rubysrc
    $ curl -0 http://ftp.ruby-lang.org/pub/ruby/1.9/ruby-1.9.3-rc1.tar.gz
  2. Extract the source code:

    $ tar xzvf ruby-1.9.3-rc1.tar.gz
    $ cd ruby-1.9.3-rc1.tar.gz
  3. Run configure and make as before. Again we need to be careful with the --prefix path. This time it should point to the RC:

    $ ./configure --prefix=$HOME/.rbenv/versions/1.9.3-rc1
    $ make
    $ make install
    $ rbenv rehash
  4. Check to see that we do indeed have 2 versions of Ruby at our disposal:

    $ rbenv versions

Version Control

Now that we’ve got 2 versions of Ruby installed how can we control which one is used? Easy. We can use rbenv global, rbenv local or rbenv shell

  1. rbenv global sets the global version of Ruby to be used by default. We’re going to set version 1.9.2 to be our global rather than using the RC by default:

    $ rbenv global 1.9.2-p290

This will write the version we choose as our global to ~/.rbenv/version

$ cat ~/.rbenv/version
    1.9.2-p290 (set by /home/ianoxley/.rbenv/version)
  1. rbenv local sets which Ruby is used on a per-project basis. For example, if we want to use RC1 in our current project foobar we’ll need to enter the following at the command line:

    $ cd ~/projects/foobar
    $ rbenv local 1.9.3-rc1

This writes the version to a file .rbenv-version in the current directory (which is why we changed directory into our project’s root folder first above):

$ cat .rbenv-version
  1. It’s also possible to use a shell-specific version of Ruby that is independent of the global or project settings. Perhaps we want to try out something using the latest nightly snapshot build of Ruby?

    $ cd ~/rubysrc
    $ curl -O http://ftp.ruby-lang.org/pub/ruby/snapshot.tar.gz
    $ tar xzvf snapshot-20111004
    $ cd snapshot-20111004
    $ ./configure --prefix=$HOME/.rbenv/versions/snapshot-20111004
    $ make
    $ make install
    $ rbenv rehash

    We can then set this to be used in our current shell like so:

    $ rbenv shell snapshot-20111004

Behind the scenes this sets the RBENV_VERSION environment variable to point to the Ruby version we tell it to:


It can be unset with:

$ rbenv shell --unset

To see all the versions of Ruby you have installed and available to rbenv there’s the rbenv versions command. This lists all the versions of Ruby that rbenv knows about and adds an asterisk next to the current active version based on the current context e.g. shell, local or global. Lets see how the output of this command changes as we change the context we’re in:

$ cd
    $ rbenv versions
    * 1.9.2-p290 (set by /home/ianoxley/.rbenv/version)

    $ cd projects/foobar
    $ rbenv versions
    *   1.9.3-rc1 (set by /home/ianoxley/projects/foobar/.rbenv-version)

    $ rbenv shell snapshot-20111004
    $ rbenv versions
    *   snapshot-20111004 (set by RBENV_VERSION environment variable)

Hopefully that all went well? If you had any problems let me know in the comments and I’ll do my best to help you out.