Skip to content

Instantly share code, notes, and snippets.

Created April 17, 2012 18:11
Show Gist options
  • Save MicahElliott/2407918 to your computer and use it in GitHub Desktop.
Save MicahElliott/2407918 to your computer and use it in GitHub Desktop.
Setting up and installing rbenv, ruby-build, rubies, rbenv-gemset, and bundler

Setting up and installing rbenv, ruby-build, rubies, rbenv-gemset, and bundler

This guide enables you to install (ruby-build) and use (rbenv) multiple versions of ruby, isolate project gems (gemsets and/or bundler), and automatically use appropriate combinations of rubies and gems.

TL;DR Demo

# Ensure system is in ship-shape.
aptitude install git zsh libssl-dev zlib1g-dev libreadline-dev libyaml-dev

# Install rbenv for managing enabling of multiple rubies.
git clone git:// ~/.rbenv
echo 'export PATH="$HOME/.rbenv/bin:$PATH"' >> ~/.zshrc
echo 'eval "$(rbenv init -)"' >> ~/.zshrc
exec $SHELL

# Install the ruby-build plugin for easy building of rubies.
mkdir -p ~/.rbenv/plugins
cd !$
git clone git://
cd where/ever

# Install a couple rubies
rbenv install 1.8.7-p358
rbenv install 1.9.3-p125
rbenv rehash
# Try out a ruby.
rbenv shell 1.9.3-p125
# Enable a newly installed ruby, persistently, globally.
rbenv global 1.9.3-p125
# Enable a ruby persistently just for this directory.
rbenv local 1.8.7-p358
rbenv rehash

# Install bundler, create a Gemfile, install to project.
gem install bundler
>Gemfile <<<'gem "ronn"'
bundle install --path vendor
bundle exec gem env

# (OPTIONAL: for those who maintain gems or have myriad projects)
# Install rbenv-gemset, create a gemset, install a gem, use it.
cd ~/.rbenv/plugins
git clone git://
rbenv gemset create 1.9.3-p125 helloset
>.rbenv-gemsets <<<helloset
rbenv gemset active
gem install ronn
rbenv rehash
rbenv gemset list

Continue reading for explanations and a few more goodies…


This covers the process of setting up rbenv and its plugins, and also touches on moving from RVM to rbenv. This is suited for development environments, but not needed for production. This does not include anything about rails (but does ensure you’re well set up and configured to install it). And none of this should require sudo. You may want to consult the individual project pages at some point to learn more, but this guide should contain — standalone — every setup instruction needed for all the tools to work.

The two things to accomplish:

  1. Having at least one reliable locally installed non-system Ruby
  2. Project-specific Gemsets OR project-local gems

These steps have been tested primarily on Arch and Ubuntu linux. Examples are using some simple Zsh syntax which is slightly different from bash.

I’ve loved using RVM. It did do a surreptitious thing with my environment (a shell file clobber setting) that I still don’t have a handle on (beyond overriding things with shell functions). And it’s a little too sophisticated to keep in my head everything it’s doing. If rbenv can eliminate any of the magic of environment management, then I’ll give it a go.

My experience is also proving that most of this setup is not necessary for servers. There it’s working out best to just install an up-to-date ruby from source (via Sprinkle).

Install rbenv

Git it.

% git clone git:// ~/.rbenv

Enable it.

% echo 'export PATH="$HOME/.rbenv/bin:$PATH"' >> ~/.zshrc
% echo 'eval "$(rbenv init -)"' >> ~/.zshrc  # or equivalent
% exec $SHELL

You haven’t done anything interesting yet. Hang tight.

For more rationale details, consult the rbenv project page.

Install the related ruby-build ruby installer

Your system should have gcc et al installed already. In Ubuntu this is build-essential and in Arch you’ve already got them, of course.

Install Ruby-Build:

% mkdir -p ~/.rbenv/plugins
% cd ~/.rbenv/plugins
% git clone git://

Now we’re done manually installing things to specific places. Ruby-Build will do the rest of the dirty work to configure, make, install, etc.

% cd ~/anywhere

Install rubies

Packages you’ll want installed in order for your rubies to configure to their fullest potential (apt packages):

libssl-dev zlib1g-dev libreadline-dev libyaml-dev flex gettext

Find out which rubies are available. Wow, you can even tab-complete these:

% rbenv install 1.8.7-p«tab»
1.8.7-p249  1.8.7-p302  1.8.7-p334  1.8.7-p352  1.8.7-p357  1.8.7-p358

Get a few (be patient):

% rbenv install 1.9.3-p125
% rbenv install jruby-1.6.7
% rbenv install rbx-2.0.0  # rubinius; why not

You need to “rehash” to regenerate rbenv’s ruby “shim” after installing a new ruby.

% rbenv rehash

Now do it again for practice:

% rbenv rehash

You’re going to do that almost every time you install a gem to generate shims for executables. Get used to it or make rbenv install an alias to also rehash:

# Abbreviation for "gem install".
gi() { gem install $@; rbenv rehash; rehash }

You’ve probably already got a system ruby installed. See them all now. (I believe system ruby is not listed here.)

% rbenv versions
  1.9.3-p125 (set by /home/mde/.rbenv/version)

You should know that these are all being installed to your ~/.rbenv/versions dir.

Turn one on for persistent “global” use across your system (for your user anyway).

NOTE: RVM users: forget the verb use. Your new enablers are shell, global, and local.

% rbenv global jruby-1.6.7
% ruby -ve 'puts "it works"'
jruby 1.6.7 (ruby-1.8.7-p357) (2012-02-22 3e82bc8) (Java HotSpot(TM)…
it works

Quickly switch back and forth in a session with: rbenv shell 1.«tab»

The local command is pretty cool — it lets you auto-enable a specific ruby whenever you enter a directory.

% <.rbenv-version
zsh: no such file or directory: .rbenv-version
% rbenv local 1.9.3-p194
% <.rbenv-version

It does so silently, so you might want to do something with your prompt to indicate what’s active.

% cd ..; cd -
<silently enabling 1.9.3-p194>

(If you intend to install ruby 1.8.7, you might or might not need this workaround.)

Enable RVM-style “gemsets” (optional)

You can skip this section and go directly the next Bundler section if you want to just always install gems directly into your projects.

Use the rbenv “plugin” subtool rbenv-gemset.

% cd ~/.rbenv/plugins
% git clone git://

You should now have a new gemset command in rbenv:

% rbenv gemset «tab»
active   create   delete   file     list     version

% rbenv gemset create 1.9.3-p125 helloset

NOTE: tab-completion is not yet working for the gemset command.

That set up a directory for you in ~/.rbenv/versions/1.9.3-p125/gemsets/helloset. But now it’s up to you to do the other half manually: setting the name of your gemset. You need to create a tiny file, in this case containing helloset.

% >.rbenv-gemsets

Now when you gem install (see “Bundler” section below) something it will go to your helloset gem area.

You can combine use of multiple gemsets with it.

The big benefit to this setup is enabling each project to use a different set of differently versioned gems.

Set up to use a gemset in a project

% cd $TMPDIR/hello

% >.rbenv-gemsets

Set up Bundler for dependency management

Bundler is the tool for managing your project dependencies. In fact, we’ll (almost) never even install a gem directly, without Bundler. It even obviates the need for gemsets for many project use cases.

NOTE: Although the tool is called “Bundler,” its command is actually bundle. This has caused some confusion. You’ll actually be fine whether you install the bundle or bundler gem, but the command will always be bundle.

Now that you’re working with multiple rubies, every ruby will need its own bundler.

Now, what gem do we actually have?

% whence -av gem
gem is /home/mde/.rbenv/shims/gem
gem is /usr/bin/gem

That didn’t make it too clear. Every ruby actually provides its own gem command (er, maybe not 1.8?). Here’s how to see it:

% rbenv which gem

And what Bundler?

% rbenv which bundle
rbenv: bundle: command not found

Hmm. Now we can see that we need to install it manually. So this is bootstrapping; it’ll be the only time we need to use gem directly for installing. (bundler is also a good global gemset install; see below.)

% gem install bundler

% rbenv which bundle

Great. That was quick and easy.

% which -a bundle
bundle is /home/mde/.rbenv/shims/bundle
bundle is /usr/bin/bundle

Now do it for all your rubies (and every time you install another ruby).

Global gemsets

Like RVM, rbenv can do global gemsets, too (though I haven’t tried it yet).

Install stuff for your project (finally)

% >Gemfile
source ""
gem "ronn", "1.3.2"
gem "nokogiri"

% bundle install

Typical workflow (demo)

% cd ~/proj/foo
% rbenv shell 1.9.3-p125
% rbenv local «tab»
1.8.7-p358  1.9.3-p125   jruby-1.6.7   rbx-2.0.0-dev  system   --unset
% rbenv local jruby-1.6.7

Set a local persistent version.

% rbenv local rbx-2.0.0-dev
% cat .rbenv-version

Speeding things up a tad

rbenv is a handful to be typing often. I presently use:

% alias rb=rbenv

though r and b are terribly distant to type on QWERTY.


Eventually new rubies will release and you’ll want to keep up. This means moving your installed gems along with them.


Set up an informative rbenv-aware prompt (optional)

Copy link

Thanks for this! It helped me out! (jf/rbenv-gemset#26)

Copy link

No problem, Ian. Thanks for reporting. I was hoping someone would find it helpful. I'll expand a bit when the next ruby 1.9.3 patch arrives. There are some interesting bits about 1.9.1+ all being C-API compatible, and things being hard wired for 1.9.1 paths, so that should be added too.

Copy link

Thank you. I didn't understand one part: "You need to create a tiny file, in this case containing helloset."

Where do I create this file? In the project directory? Does this tell rbenv which gemset to use when cd'ing to a project?

Copy link

Thanks, very informative. Now I just need to figure out how to use rails with rbenv. Anyway, I think you are missing a semicolon in your 'bundle install' alias

# Abbreviation for "gem install".
gi() { gem install $@; rbenv rehash; rehash; }

Copy link

MtnBiker commented Jul 8, 2013

Would like "FIXME: I HAVEN'T DONE THIS YET" to see the upgrading section done.

Thanks for the good info

Copy link

MtnBiker commented Jul 9, 2013

How do I install a gem to the system Ruby? I'm asking because I'm having trouble installing the latest (and reportedly last) 1.8.7. In general, how does one control which Ruby a gem is installed with?

Copy link

Does this work for new ruby versions?

Copy link

scones commented Nov 28, 2017

If someone else finds this via google:
This GIST is outdated.

The correct rbenv is found under:

The correct ruby-build is found under:

The correct rbenv-gemset ist found under:

Otherwise you will get an rbenv, that does not known about ruby versions higher than 2.3.0-dev

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment