Using rbenv to install and maintain Ruby on macOS.
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.
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
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
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.
We use Homebrew to install and manage
You should note that
rbenv is incompatible with
RVM is another popular Ruby version management tool. Uninstall
RVM before installing
If you are using
RVM and are happy with it, then no need to change anything. But if you want to know why choose
RVM then have a look at this.
- 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
~/.bash_profileif you use bash.
echo 'export PATH="$HOME/.rbenv/bin:$PATH"' >> ~/.zshrc
rbenv initand 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
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
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
A few of the most common commands:
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
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 global 1.8.7-p352
The special version name
system tells rbenv to use the system Ruby (detected by searching your
When run without a version number,
rbenv global reports the currently configured global version.
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
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)
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
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.