Ruby version management (rbenv, rvm) - Deep Dive

Overview - Ruby version management (rbenv, rvm)

What is it?

Ruby version management is a way to easily switch between different versions of the Ruby programming language on the same computer. Tools like rbenv and rvm help you install, manage, and use multiple Ruby versions without conflicts. This is useful because different projects may need different Ruby versions to work correctly. Without version management, you would have to manually change settings or risk breaking your projects.

Why it matters

Without Ruby version management, developers would struggle to maintain projects that depend on different Ruby versions. This can cause errors, wasted time fixing conflicts, and difficulty collaborating with others. Version managers solve this by letting you switch Ruby versions quickly and safely, making development smoother and more reliable. This means less frustration and more focus on building great software.

Where it fits

Before learning Ruby version management, you should understand basic Ruby installation and command line usage. After mastering version management, you can explore Ruby gem management and project environment tools like Bundler. This topic fits early in your Ruby development setup journey, enabling better project compatibility and workflow.

Mental Model

Core Idea

Ruby version management tools act like a remote control that lets you switch between different Ruby versions on your computer instantly.

Think of it like...

Imagine you have several TV channels (Ruby versions) but only one TV (your computer). A remote control (rbenv or rvm) lets you switch channels easily without unplugging or rewiring anything.

┌───────────────┐
│ Your Computer │
└──────┬────────┘
       │
       ▼
┌───────────────┐     ┌───────────────┐     ┌───────────────┐
│ Ruby Version 1│     │ Ruby Version 2│     │ Ruby Version 3│
└───────────────┘     └───────────────┘     └───────────────┘
       ▲                   ▲                   ▲
       │                   │                   │
   ┌───┴───┐           ┌───┴───┐           ┌───┴───┐
   │ rbenv │           │  rvm  │           │  User │
   └───────┘           └───────┘           └───────┘

User uses rbenv or rvm to select which Ruby version runs.

Build-Up - 6 Steps

1

Foundation

What is Ruby version management?

Concept: Introducing the basic idea of managing multiple Ruby versions on one machine.

Ruby version management means using tools to install and switch between different Ruby versions easily. This helps when you have projects that need different Ruby versions. Instead of uninstalling and reinstalling Ruby each time, you use a manager to handle this for you.

Result

You understand why managing Ruby versions is necessary and what problem it solves.

Understanding the need for version management prevents confusion when projects require different Ruby versions.

2

Foundation

Installing rbenv and rvm basics

Concept: Learn how to install the two main Ruby version managers: rbenv and rvm.

rbenv and rvm are tools you install on your computer. rbenv is lightweight and focuses on switching Ruby versions, while rvm is more feature-rich and can manage gemsets too. Installation usually involves running commands in your terminal and updating your shell configuration.

Result

You have rbenv or rvm installed and ready to use on your system.

Knowing how to install these tools is the first step to managing Ruby versions effectively.

3

Intermediate

Switching Ruby versions per project

🤔Before reading on: do you think switching Ruby versions affects all projects globally or can it be done per project? Commit to your answer.

Concept: Learn how to set Ruby versions globally or locally for specific projects using version managers.

With rbenv, you can set a global Ruby version that applies everywhere, or a local version that applies only inside a project folder by creating a .ruby-version file. rvm uses gemsets and can also switch versions per terminal session or project. This lets you work on multiple projects with different Ruby versions without conflicts.

Result

You can run different Ruby versions in different projects seamlessly.

Understanding local vs global version settings helps avoid version conflicts and keeps projects stable.

4

Intermediate

Managing gems with version managers

🤔Before reading on: do you think gems installed in one Ruby version are available in others? Commit to your answer.

Concept: Explore how gems (Ruby libraries) are managed separately for each Ruby version and gemset.

Each Ruby version has its own set of installed gems. rvm adds gemsets to isolate gems further within the same Ruby version. This means you can have different gems for different projects without interference. You install gems after switching to the correct Ruby version or gemset.

Result

You avoid gem conflicts and keep project dependencies clean.

Knowing gem isolation prevents bugs caused by incompatible or missing gems across projects.

5

Advanced

How rbenv shims Ruby commands

🤔Before reading on: do you think rbenv replaces Ruby binaries or uses a different method to switch versions? Commit to your answer.

Concept: Understand the shim system rbenv uses to intercept Ruby commands and redirect to the correct version.

rbenv works by placing 'shims'—small wrapper scripts—in your PATH. When you run 'ruby' or 'gem', the shim checks which Ruby version is active and runs the correct binary. This avoids replacing system Ruby and allows easy switching without changing environment variables manually.

Result

You grasp how rbenv switches Ruby versions transparently.

Understanding shims explains why rbenv is lightweight and less intrusive than other managers.

6

Expert

RVM internals and gemset isolation

🤔Before reading on: do you think RVM gemsets share gems or keep them fully separate? Commit to your answer.

Concept: Dive into how RVM creates isolated gem environments called gemsets and manages Ruby installations internally.

RVM installs Ruby versions in its own directory and creates gemsets as separate folders inside each Ruby version. Each gemset has its own gems, allowing multiple projects to use different gems even if they share the same Ruby version. RVM also modifies shell environment variables to switch versions and gemsets dynamically.

Result

You understand how RVM provides powerful isolation for complex Ruby projects.

Knowing RVM internals helps troubleshoot environment issues and optimize project setups.

Under the Hood

rbenv works by inserting shims into your command path that intercept Ruby commands and redirect them to the selected Ruby version's binaries. It reads version settings from files or environment variables to decide which Ruby to run. RVM, on the other hand, installs Ruby versions and gemsets in isolated directories and modifies shell environment variables like PATH and GEM_HOME to switch contexts. Both avoid overwriting system Ruby and allow multiple versions to coexist.

Why designed this way?

These tools were created to solve the problem of conflicting Ruby versions on one machine, especially when system Ruby is needed for OS tasks. rbenv was designed to be simple and minimal, avoiding heavy shell modifications. RVM aimed to be a full-featured environment manager including gem isolation. Alternatives like manually changing PATH or uninstalling Ruby were error-prone and inefficient.

User Terminal
   │
   ▼
┌───────────────┐
│ rbenv Shims   │ <─ intercept commands like 'ruby', 'gem'
└──────┬────────┘
       │
       ▼
┌───────────────┐
│ Selected Ruby │
│ Version Bin   │
└───────────────┘

OR

User Terminal
   │
   ▼
┌───────────────┐
│ RVM Shell Env │ <─ sets PATH, GEM_HOME
└──────┬────────┘
       │
       ▼
┌───────────────┐
│ Ruby Version  │
│ + Gemset Dir  │
└───────────────┘

Myth Busters - 4 Common Misconceptions

Quick: Does installing a new Ruby version with rbenv automatically make it the default? Commit to yes or no.

Common Belief: Installing a Ruby version with rbenv or rvm automatically switches your system to use it everywhere.

Reality: Installing a Ruby version only makes it available; you must explicitly set it as global or local to use it by default.

Why it matters: Assuming automatic switching leads to confusion when your Ruby version doesn't change as expected, causing project errors.

Quick: Are gems shared across all Ruby versions by default? Commit to yes or no.

Common Belief: Gems installed in one Ruby version are available in all other Ruby versions automatically.

Reality: Each Ruby version has its own separate gem directory; gems are not shared unless manually copied or linked.

Why it matters: Expecting shared gems can cause missing gem errors or version conflicts in projects.

Quick: Does rbenv replace the system Ruby installation? Commit to yes or no.

Common Belief: rbenv replaces or overwrites the system Ruby installation when managing versions.

Reality: rbenv never replaces system Ruby; it uses shims to select Ruby versions without altering system files.

Why it matters: Misunderstanding this can lead to unnecessary fear of breaking system tools or improper uninstall attempts.

Quick: Does RVM gemset isolation mean gems are completely independent? Commit to yes or no.

Common Belief: RVM gemsets share gems between each other to save space and avoid duplication.

Reality: RVM gemsets are fully isolated; gems installed in one gemset are not visible in others.

Why it matters: Assuming shared gems can cause confusion when gems seem missing or duplicated across projects.

Expert Zone

1

rbenv's shim system relies on your PATH order, so misconfiguring PATH can cause unexpected Ruby versions to run.

2

RVM modifies shell environment variables dynamically, which can cause conflicts with other environment managers if not carefully handled.

3

Using gemsets in RVM adds complexity but allows fine-grained control over gem dependencies per project, which is crucial in large codebases.

When NOT to use

If you only work on a single Ruby version or use containerized environments like Docker that isolate Ruby versions, using rbenv or RVM may be unnecessary. Alternatives include chruby for simpler switching or system package managers for fixed Ruby versions.

Production Patterns

In production, Ruby version managers are often used in development and testing environments but not on servers, where a fixed Ruby version is installed system-wide. Continuous integration pipelines use version managers to test code against multiple Ruby versions automatically. Developers use rbenv for lightweight switching and RVM when gemset isolation is needed.

Connections

Python virtual environments

Similar pattern of isolating language versions and dependencies

Understanding Ruby version managers helps grasp Python's virtualenv or pyenv tools, as both solve similar problems in different languages.

Operating system PATH variable

Version managers manipulate PATH to control which Ruby executable runs

Knowing how PATH works clarifies how rbenv shims and RVM environment changes affect command execution.

Software containerization (Docker)

Alternative approach to version isolation by packaging entire environments

Comparing version managers to containers shows different strategies for managing software dependencies and versions.

Common Pitfalls

#1 Forgetting to set a local Ruby version for a project

Wrong approach:

cd my_project
ruby -v # runs wrong Ruby version
# no .ruby-version file set

Correct approach:

cd my_project
rbenv local 2.7.4
ruby -v # runs Ruby 2.7.4 as expected

Root cause:

Not understanding that rbenv uses .ruby-version files to switch Ruby versions per project.

#2 Installing gems without switching to the correct Ruby version

Wrong approach:

gem install rails
# but current Ruby is wrong version

Correct approach:

rbenv shell 3.0.0
gem install rails
# gems installed for Ruby 3.0.0

Root cause:

Not realizing gems are installed per Ruby version, so installing under wrong version causes missing gems.

#3 Mixing rbenv and RVM without proper configuration

Wrong approach:

Installing both rbenv and RVM and expecting them to work seamlessly together without adjusting PATH

Correct approach:

Choose one version manager and configure shell environment properly to avoid conflicts.

Root cause:

Lack of understanding that both tools modify environment and can conflict if used simultaneously.

Key Takeaways

Ruby version management tools like rbenv and RVM let you switch Ruby versions easily to support multiple projects.

rbenv uses lightweight shims to redirect Ruby commands, while RVM provides gemset isolation and environment control.

Each Ruby version has its own gems; managing versions and gems separately prevents conflicts and errors.

Setting local Ruby versions per project avoids unexpected version mismatches during development.

Understanding how these tools work under the hood helps troubleshoot issues and optimize your Ruby environment.