Using rbenv to install and maintain Ruby on macOS.

October 09, 2017

I haven't learned Ruby but I do use Bundler it's dependency management programme. While trying to update the previous post I ran across a problem with Ruby, for which I spent more than 30 minutes to find and try the solutions. I did find the solution that worked - reinstalling Ruby. But this time I used a Ruby version management tool rbenv.

The problem

This blog is created using Jekyll on a Mac. Mac comes with Ruby pre-installed, but this version of Ruby is usually old. My system(macOS) Ruby version is at v2.0.0 while the latest stable release is at v2.4.2.

Using ruby -v I get the following result.

$ ruby -v
ruby 2.0.0p648 (2015-12-16 revision 53162) [universal.x86_64-darwin16]

This is the system Ruby. The output should show me the version of Ruby I installed using Homebrew as always. Something like this :

$ ruby -v
ruby 2.4.2p198 (2017-09-13 revision 59899) [x86_64-darwin16]

I discovered the problem while updating the previous blog post. Jekyll itself is a Ruby gem, and all its plugins are also gems that need to be installed separately. I wanted to update gems and so I ran bundle update, but it wouldn't work. It was showing following error:

$ bundle update
ERROR: While executing gem ... (Gem::FilePermissionError)
You don't have write permissions for the /Library/Ruby/Gems/2.0.0 directory.

I don't have write permissions for the /Library/Ruby/Gems/2.0.0 directory because that's the system Ruby installation. The system Ruby is not writable by a normal user; if you want to modify the system Ruby's gems, you need to use sudo. But I don't want to use system Ruby, what happened to my Homebrew Ruby?

Honestly, I didn't dig deeper into this issue since I just wanted to get my post online and be done for the day. I decided to remove the homebrew ruby and reinstall it using rbenv . From my knowledge, unlike rvm, rbenv is not available for windows. This post will only be useful for macOS users.

Why rbenv ?

Different users can have their own global Ruby version.
You can install project specific local Ruby versions.

The rest of the post includes steps to install rbenv, install Ruby using rbenv, installing gems, upgrading rbenv and some common commands you might find useful.

Prerequisite

We use Homebrew to install and manage rbenv .

You should note that rbenv is incompatible with RVM. RVM is another popular Ruby version management tool. Uninstall RVM before installing rbenv.

If you are using RVM and are happy with it, then no need to change anything. But if you want to know why choose rbenv over RVM then have a look at this.

Installing rbenv

Installing using Homebrew

brew install rbenv

Note that this also installs ruby-build, so you'll be ready to install other Ruby versions out of the box.

Add the following PATH to ~/.zshrc or ~/.bash_profile if you use bash.

echo 'export PATH="$HOME/.rbenv/bin:$PATH"' >> ~/.zshrc

Run rbenv init and follow the instruction which is as follows :

echo 'eval "$(rbenv init -)"' >> ~/.zshrc

Restart your shell so that PATH changes take effect. (Opening a new terminal tab will usually do it.). Verify that rbenv is properly set up using this rbenv-doctor script:

curl -fsSL https://github.com/rbenv/rbenv-installer/raw/master/bin/rbenv-doctor | bash

Installing Ruby Versions

Use rbenv install to install different versions of ruby.

# list all available versions:
$ rbenv install -l

# install a Ruby version:
$ rbenv install 2.3.0

Installing Ruby Gems

Install bundler to install ruby gems.

gem install bundler

Upgrading with Homebrew

To upgrade to the latest rbenv and update ruby-build with newly released Ruby versions, upgrade the Homebrew packages:

$ brew upgrade rbenv ruby-build

Command Reference

A few of the most common commands:

rbenv local

Sets a local application-specific Ruby version by writing the version name to a .ruby-version file in the current directory. This version overrides the global version, and can be overridden itself by setting the RBENV_VERSIONenvironment variable or with the rbenv shell command.

$ rbenv local 1.9.3-p327

When run without a version number, rbenv local reports the currently configured local version. You can also unset the local version:

$ rbenv local --unset

rbenv global

Sets the global version of Ruby to be used in all shells by writing the version name to the ~/.rbenv/version file. This version can be overridden by an application-specific .ruby-version file, or by setting the RBENV_VERSIONenvironment variable.

$ rbenv global 1.8.7-p352

The special version name system tells rbenv to use the system Ruby (detected by searching your $PATH).

When run without a version number, rbenv global reports the currently configured global version.

rbenv versions

Lists all Ruby versions known to rbenv, and shows an asterisk next to the currently active version.

$ rbenv versions
  1.8.7-p352
  1.9.2-p290
* 1.9.3-p327 (set by /Users/sam/.rbenv/version)
  jruby-1.7.1
  rbx-1.2.4
  ree-1.8.7-2011.03

rbenv version

Displays the currently active Ruby version, along with information on how it was set.

$ rbenv version
1.9.3-p327 (set by /Users/sam/.rbenv/version)

rbenv rehash

Installs shims for all Ruby executables known to rbenv (i.e., ~/.rbenv/versions/*/bin/*). Run this command after you install a new version of Ruby, or install a gem that provides commands.

$ rbenv rehash

rbenv which

Displays the full path to the executable that rbenv will invoke when you run the given command.

$ rbenv which irb
/Users/sam/.rbenv/versions/1.9.3-p327/bin/irb

All these commands can be found on rbenv GitHub page. I have simply reproduced(copied 😅) it here as it is.