cyberangles guide

Ruby Version Management: A Guide to RVM and rbenv

Ruby, a dynamic, object-oriented programming language, is widely used for web development (e.g., Ruby on Rails), scripting, and automation. As Ruby evolves, new versions introduce features, performance improvements, and security patches. However, different projects often require specific Ruby versions—an older Rails app might依赖 on Ruby 2.7, while a new project could use Ruby 3.2. Managing multiple Ruby versions on a single machine can be challenging without the right tools. This is where Ruby version managers come in. They let you install, switch between, and isolate Ruby versions and their dependencies seamlessly. Two popular tools for this are **RVM (Ruby Version Manager)** and **rbenv**. In this guide, we’ll dive deep into both tools, exploring their installation, usage, features, and tradeoffs to help you choose the right one for your workflow.

Table of Contents

  1. Why Ruby Version Management Matters
  2. RVM (Ruby Version Manager)
  3. rbenv
  4. RVM vs. rbenv: A Comparison
  5. Conclusion
  6. References

Why Ruby Version Management Matters

Before diving into the tools, let’s clarify why version management is critical for Ruby developers:

  • Multiple Projects, Multiple Versions: You might work on a legacy Rails 5 app requiring Ruby 2.6 and a new Rails 7 app requiring Ruby 3.2. Without a version manager, switching between these versions manually is error-prone.
  • Avoid System Ruby Issues: Most operating systems ship with a “system Ruby” (e.g., macOS includes Ruby 2.6 by default), but modifying it can break system tools. Version managers let you install Rubies in your home directory, avoiding permission issues.
  • Dependency Isolation: Gems (Ruby libraries) installed for one project can conflict with another. Tools like RVM and rbenv help isolate gems per project or Ruby version.
  • Team Collaboration: Ensuring all team members use the same Ruby version and gem dependencies reduces “works on my machine” bugs.

RVM (Ruby Version Manager)

What is RVM?

RVM (Ruby Version Manager) is a command-line tool designed to manage multiple Ruby environments. Launched in 2009 by Wayne E. Seguin, RVM is known for its built-in gemset support and ease of use, making it a favorite for beginners and developers who want an all-in-one solution.

Installation

RVM supports Linux, macOS, and Windows (via WSL). Below are installation steps for common operating systems:

Prerequisites

Before installing RVM, ensure you have required system packages. For Ubuntu/Debian:

sudo apt-get update
sudo apt-get install -y curl gpg build-essential libssl-dev libreadline-dev zlib1g-dev

For macOS (using Homebrew):

brew install gpg

Install RVM

Use the official RVM installer script:

curl -sSL https://get.rvm.io | bash -s stable

After installation, load RVM into your current shell:

source ~/.rvm/scripts/rvm

Verify installation:

rvm --version
# Output: rvm 1.29.12 (latest) by Michal Papis, Piotr Kuczynski, Wayne E. Seguin [...]

Basic Usage

RVM simplifies common version management tasks:

Installing Ruby Versions

List all available Ruby versions:

rvm list known

Install a specific version (e.g., Ruby 3.2.2):

rvm install 3.2.2
# RVM will download, compile, and install Ruby 3.2.2

Listing Installed Rubies

View all Ruby versions installed via RVM:

rvm list
# Output:
#   ruby-2.7.6 [ x86_64 ]
# => ruby-3.2.2 [ x86_64 ]
# * system [ x86_64 ]

Switching Ruby Versions

  • Temporarily (current shell): 
    rvm use 2.7.6
  • Permanently (default for new shells): 
    rvm use 3.2.2 --default

Uninstalling a Ruby Version

rvm remove 2.7.6

Gemset Management

RVM’s standout feature is gemsets—isolated environments for gem dependencies. Gemsets let you separate gems for different projects, even if they use the same Ruby version.

Creating a Gemset

Create a gemset for a project (e.g., myapp with Ruby 3.2.2):

rvm use 3.2.2@myapp --create
# Creates and switches to the `myapp` gemset under Ruby 3.2.2

Listing Gemsets

View gemsets for the current Ruby version:

rvm gemset list
# Output:
#   (default)
#   global
# => myapp

Deleting a Gemset

rvm gemset delete myapp

Automating Gemset Selection with .rvmrc

To auto-switch to a project’s Ruby version and gemset, create an .rvmrc file in your project root:

echo "rvm use 3.2.2@myapp" > .rvmrc

When you cd into the project, RVM will prompt to trust the file (answer “yes” once).

Advanced Features

  • Hooks: Customize RVM behavior with pre/post-execution scripts (e.g., run bundle install when switching gemsets).
  • Aliases: Create shortcuts for Ruby versions (e.g., rvm alias create rails-7 3.2.2).
  • System-wide Installation: Install RVM for all users (requires root access).

Pros and Cons of RVM

ProsCons
Built-in gemset support (no extra tools needed).Heavier than rbenv (more overhead).
Simple, all-in-one installation.More intrusive (modifies shell environment deeply).
Rich documentation and community support.Less modular (hard to disable specific features).

rbenv

What is rbenv?

rbenv (Ruby Environment) is a lightweight, modular version manager created by Sam Stephenson. Unlike RVM, rbenv focuses on simplicity and minimalism, using “shims” to redirect Ruby commands to the active version. It relies on plugins for extra features (e.g., installing Rubies, gemsets).

Installation

rbenv supports Linux, macOS, and Windows (via WSL). Installation methods vary; we’ll cover the most common.

Prerequisites

Install build tools (same as RVM) plus libffi-dev (for some Ruby versions):

# Ubuntu/Debian
sudo apt-get install -y libffi-dev

# macOS (Homebrew)
brew install openssl readline libyaml gdbm libffi

Clone the rbenv repository to ~/.rbenv:

git clone https://github.com/rbenv/rbenv.git ~/.rbenv

Add ~/.rbenv/bin to your PATH and enable shims by adding this to your shell config (.bashrc, .zshrc, etc.):

echo 'export PATH="$HOME/.rbenv/bin:$PATH"' >> ~/.bashrc
echo 'eval "$(rbenv init -)"' >> ~/.bashrc
source ~/.bashrc  # Reload shell

Install ruby-build (Critical Plugin)

rbenv itself doesn’t install Ruby versions—use ruby-build, a plugin that adds rbenv install functionality:

git clone https://github.com/rbenv/ruby-build.git ~/.rbenv/plugins/ruby-build
echo 'export PATH="$HOME/.rbenv/plugins/ruby-build/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc

Verify Installation

rbenv --version
# Output: rbenv 1.2.0

Basic Usage

Installing Ruby Versions

List available Ruby versions (via ruby-build):

rbenv install -l  # List stable versions

Install a Ruby version (e.g., 3.2.2):

rbenv install 3.2.2
# ruby-build will download, compile, and install Ruby 3.2.2 to ~/.rbenv/versions/3.2.2

Listing Installed Rubies

rbenv versions
# Output:
#   system
# * 3.2.2 (set by /home/user/.rbenv/version)

Switching Ruby Versions

rbenv uses three scopes for version selection:

  • Global: Default for all shells (set in ~/.rbenv/version):

    rbenv global 3.2.2

  • Local: Project-specific (set in ./.ruby-version):

    rbenv local 2.7.6  # Creates a .ruby-version file in the current directory

  • Shell: Temporary (current shell only):

    rbenv shell 3.1.4

Uninstalling a Ruby Version

rbenv uninstall 2.7.6

Gem Management with rbenv

rbenv doesn’t include built-in gemsets, but you can manage dependencies in two ways:

1. Bundler with --path

Use Bundler to install gems locally in your project:

bundle install --path vendor/bundle

This creates a vendor/bundle directory with project-specific gems.

2. rbenv-gemset Plugin

For gemset-like isolation, install the rbenv-gemset plugin:

git clone https://github.com/jf/rbenv-gemset.git ~/.rbenv/plugins/rbenv-gemset

Create a .ruby-gemset file in your project:

echo "myapp" > .ruby-gemset

Now gems installed with gem install will be isolated to the myapp gemset.

Advanced Features

  • Shims Explained: rbenv uses “shims” (small executables in ~/.rbenv/shims) to intercept Ruby commands (e.g., ruby, gem, bundle). When you run ruby, the shim checks the active version and runs the corresponding binary.
  • Plugins: Extend rbenv with plugins like:
    • ruby-build: Install Rubies (essential).
    • rbenv-gemset: Add gemset support.
    • rbenv-vars: Load environment variables from .rbenv-vars.
  • Hooks: Run scripts before/after rbenv commands (e.g., after_install to run bundle install).

Pros and Cons of rbenv

ProsCons
Lightweight (minimal shell overhead).Requires plugins for core features (e.g., ruby-build).
Non-intrusive (modifies shell lightly).No built-in gemsets (needs rbenv-gemset).
Simple, readable codebase (easy to debug).Steeper initial setup (manual plugin configuration).
Modular (add features only when needed).Less documentation than RVM.

RVM vs. rbenv: A Comparison

Choosing between RVM and rbenv depends on your workflow. Here’s a head-to-head:

FeatureRVMrbenv
InstallationOne-liner script (all-in-one).Git clone + plugin setup (modular).
Gem ManagementBuilt-in gemsets (no extra tools).Requires rbenv-gemset or Bundler.
PerformanceSlightly slower (more shell modifications).Faster (minimal shim overhead).
EcosystemRich, but monolithic.Modular (plugins for everything).
Use CaseBeginners, teams wanting simplicity.Advanced users, minimalists, CI/CD.

Recommendation:

  • Use RVM if you want built-in gemsets, a simple install, and don’t mind slightly more overhead.
  • Use rbenv if you prefer lightweight tools, modularity, or work in environments where minimalism is critical (e.g., servers).

Conclusion

Ruby version management is non-negotiable for modern development. Both RVM and rbenv solve the core problem of managing multiple Ruby versions, but they cater to different preferences: RVM prioritizes convenience, while rbenv emphasizes simplicity.

Whichever tool you choose, the goal is the same: consistent, isolated environments that let you focus on building great Ruby applications. Experiment with both to see which aligns with your workflow—you can even switch later (uninstalling either is straightforward).

References