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
andmake 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
folderThe 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
andmake
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 projectfoobar
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.
Ian Oxley has been building stuff on the Web professionally since 2004. He lives and works in Newcastle-upon-Tyne, England, and often attends local user groups and meetups. He's been known to speak at them on occasion too. When he's not in front of a computer Ian can be found playing guitar, and taking photos. But not usually at the same time.