Up and Running with rbenv

Key Takeaways

rbenv is a lightweight tool that allows for the installation and running of multiple versions of Ruby side-by-side, focusing solely on managing multiple Ruby environments.
The installation process of rbenv requires each version of Ruby to be installed in the ~/.rbenv/versions directory, with shims used to switch between versions.
rbenv allows for global and per-project level control of Ruby versions, which can be overridden with environment variables. It does not override any built-in shell commands or come with any mechanism to install versions of Ruby.
While similar to RVM, rbenv differs in that it does not provide built-in support for installing Rubies, does not come with a flexible gem management system, and does not allow for testing against multiple Ruby versions simultaneously.

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.

Installation

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:

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
```
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
```
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
```
If we restart our shell we’ll have rbenv and autocompletion available straight away:
```
$ exec $SHELL
```
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
```

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

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

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
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:

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

Extract the source code:

$ tar xzvf ruby-1.9.3-rc1.tar.gz
$ cd ruby-1.9.3-rc1.tar.gz

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
```
Check to see that we do indeed have 2 versions of Ruby at our disposal:
```
$ rbenv versions
    1.9.2-p290
    1.9.3-rc1
```

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

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)

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.9.3-rc1

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:

$ echo $RBENV_VERSION
    snapshot-20111004

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)
        1.9.3-rc1
        snapshot-20111004

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

    $ rbenv shell snapshot-20111004
    $ rbenv versions
        1.9.2-p290
        1.9.3-rc1
    *   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.

Frequently Asked Questions (FAQs) about rbenv

How does rbenv work in managing different Ruby versions?

rbenv is a version manager for Ruby that allows you to switch between different versions of Ruby on your system. It works by inserting a directory of shims at the front of your PATH. When you execute a Ruby command, it passes through the shim layer, which determines which Ruby version has been specified by your application, and passes the command along to the corresponding Ruby interpreter.

How do I install rbenv on macOS?

To install rbenv on macOS, you can use Homebrew. Open your terminal and type brew install rbenv. After the installation, you need to add rbenv to bash so that it loads every time you open a Terminal. You can do this by typing echo 'if which rbenv > /dev/null; then eval "$(rbenv init -)"; fi' >> ~/.bash_profile. Then, restart your terminal.

How do I set a global Ruby version with rbenv?

To set a global Ruby version with rbenv, you can use the rbenv global command followed by the version number. For example, rbenv global 2.7.1 will set Ruby 2.7.1 as the global version. This version will be used in all your shell sessions.

How can I list all available Ruby versions with rbenv?

You can list all available Ruby versions with rbenv by using the rbenv install -l command. This will display a list of all Ruby versions that you can install.

How do I uninstall a Ruby version with rbenv?

To uninstall a Ruby version with rbenv, you can use the rbenv uninstall command followed by the version number. For example, rbenv uninstall 2.7.1 will uninstall Ruby 2.7.1 from your system.

How do I update rbenv and its plugins?

To update rbenv and its plugins, you can use git. Navigate to the rbenv directory (cd ~/.rbenv) and then pull the latest changes (git pull). To update plugins, navigate to each plugin directory and pull the latest changes.

How do I use rbenv with Rails?

To use rbenv with Rails, first ensure that the correct Ruby version is installed and set as the global version. Then, install the Rails gem for that Ruby version using the gem install rails command. rbenv will ensure that Rails runs with the correct Ruby version.

How do I troubleshoot common rbenv issues?

Common rbenv issues can often be resolved by rehashing the shims (rbenv rehash). If you’re still having issues, ensure that rbenv is properly initialized in your shell, and that the correct Ruby version is set.

How do I install a new Ruby version with rbenv?

To install a new Ruby version with rbenv, use the rbenv install command followed by the version number. For example, rbenv install 2.7.1 will install Ruby 2.7.1. After installation, you can set it as the global version with the rbenv global command.

How does rbenv compare to other Ruby version managers?

rbenv is similar to other Ruby version managers like RVM, but it’s more lightweight and less intrusive. It doesn’t override shell commands or manage gemsets. Instead, it uses shims to intercept Ruby commands and determine which version to use. This makes it a bit more flexible and less likely to cause conflicts with other software.