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.

Practice

1. What is the main purpose of using Ruby version managers like rbenv or rvm?

easy

A. To debug Ruby code automatically

B. To write Ruby code faster

C. To compile Ruby programs into executables

D. To switch between different Ruby versions easily

Solution

1. Step 1: Understand Ruby version managers

   Ruby version managers like rbenv and rvm allow you to install and switch between multiple Ruby versions on the same machine.

2. Step 2: Identify the main use

   The main use is to switch Ruby versions easily without affecting other projects or the system Ruby.

3. Final Answer:

   To switch between different Ruby versions easily -> Option D

4. Quick Check:

   Ruby version managers help switch versions = D [OK]

Hint: Remember: rbenv and rvm manage Ruby versions [OK]

Common Mistakes:

• Thinking they speed up coding
• Confusing with debugging tools
• Assuming they compile Ruby code

2. Which of the following commands correctly sets the global Ruby version to 3.1.2 using rbenv?

easy

A. rbenv global 3.1.2

B. rbenv use 3.1.2

C. rbenv set 3.1.2

D. rbenv switch 3.1.2

Solution

1. Step 1: Recall rbenv commands

   The command to set the global Ruby version in rbenv is rbenv global <version>.

2. Step 2: Match the correct command

   Among the options, only rbenv global 3.1.2 correctly sets the global version.

3. Final Answer:

   rbenv global 3.1.2 -> Option A

4. Quick Check:

   Set global version = rbenv global [OK]

Hint: Use 'rbenv global' to set Ruby version globally [OK]

Common Mistakes:

• Using 'rbenv use' which is invalid
• Confusing 'set' or 'switch' commands
• Not specifying the version number

3. Given the following commands run in order:
rbenv install 3.0.0
rbenv local 3.0.0
ruby -v
What will be the output of ruby -v?

medium

A. ruby 2.7.0 (system default)

B. Command not found error

C. ruby 3.0.0 (installed version)

D. ruby 3.1.0 (latest version)

Solution

1. Step 1: Understand the commands

   rbenv install 3.0.0 installs Ruby 3.0.0. rbenv local 3.0.0 sets the Ruby version to 3.0.0 for the current directory.

2. Step 2: Predict the ruby version output

   Running ruby -v in that directory will use Ruby 3.0.0, showing its version.

3. Final Answer:

   ruby 3.0.0 (installed version) -> Option C

4. Quick Check:

   Local version set to 3.0.0 means ruby -v shows 3.0.0 [OK]

Hint: Local version overrides system Ruby version [OK]

Common Mistakes:

• Assuming system default Ruby is used
• Expecting latest Ruby version output
• Thinking command will fail without global set

4. You run rvm use 2.7.0 but get the error: RVM is not a function, selecting rubies with 'rvm use ...' will not work.
What is the most likely cause?

medium

A. RVM is not installed

B. You did not load RVM as a shell function

C. Ruby 2.7.0 is not installed

D. You need to restart your computer

Solution

1. Step 1: Understand the error message

   The error says 'RVM is not a function', which means the shell does not recognize RVM commands properly.

2. Step 2: Identify cause

   This usually happens if the RVM script is not sourced in the shell, so RVM commands are not loaded as functions.

3. Final Answer:

   You did not load RVM as a shell function -> Option B

4. Quick Check:

   Load RVM script in shell to fix 'not a function' error [OK]

Hint: Always source RVM script in your shell config [OK]

Common Mistakes:

• Assuming RVM is not installed at all
• Thinking Ruby version is missing
• Restarting computer unnecessarily

5. You want to create a project that uses Ruby 3.2.0 but your system default is Ruby 2.6.3. Using rbenv, which sequence of commands correctly sets up your project to use Ruby 3.2.0 locally without affecting other projects?

hard

A. rbenv install 3.2.0rbenv local 3.2.0

B. rbenv local 3.2.0rbenv install 3.2.0

C. rbenv install 3.2.0rbenv global 3.2.0

D. rbenv global 3.2.0rbenv install 3.2.0

Solution

1. Step 1: Install Ruby 3.2.0 first

   You must install Ruby 3.2.0 before using it. So rbenv install 3.2.0 is first.

2. Step 2: Set local version for project

   To use Ruby 3.2.0 only in the project folder, use rbenv local 3.2.0. This does not affect other projects or the global version.

3. Final Answer:

   rbenv install 3.2.0
   rbenv local 3.2.0 -> Option A

4. Quick Check:

   Install then set local version for project isolation [OK]

Hint: Install Ruby first, then set local version for project [OK]

Common Mistakes:

• Setting global version instead of local
• Setting local version before installing Ruby
• Assuming global affects only one project