Why rbenv Is Not Changing Ruby Version on macOS or Ubuntu

By the end of this page, you will understand how rbenv selects a Ruby version, why which ruby may still point to /usr/bin/ruby, and how shell configuration and PATH determine whether rbenv works correctly. You will also learn how to diagnose and fix common rbenv setup problems on macOS and Linux.

rbenv does not replace the system Ruby directly. Instead, it works by placing shims at the front of your shell's PATH.

A shim is a small executable that stands in front of the real command. When you run a command like ruby, gem, or bundle, the shim asks rbenv which Ruby version should be active, then forwards the command to the correct Ruby installation.

If your shell is still finding /usr/bin/ruby, that means the rbenv shims are not being used first in PATH. In that case:

• rbenv global may still show the version you selected
• rbenv versions may still list installed Rubies
• but ruby -v will keep showing the system Ruby

This is why rbenv can look correctly configured at first glance while not actually affecting the Ruby that runs.

The key idea is:

• rbenv stores version settings
• shell PATH decides whether those settings are used

Think of rbenv as a receptionist in front of several Ruby installations.

When you type ruby, your shell looks for the first ruby it can find.

• If it reaches /usr/bin/ruby first, you get the system Ruby.
• If it reaches the rbenv shim first, the receptionist checks your configured version and sends you to the correct Ruby.

So the problem is usually not that rbenv forgot your chosen version. The problem is that the shell never asked rbenv in the first place.

The most important rbenv commands are:

rbenv versions
rbenv global 3.2.2
rbenv local 3.2.2
rbenv shell 3.2.2
rbenv rehash
rbenv which ruby

A typical shell setup looks like this:

export PATH="$HOME/.rbenv/bin:$PATH"
eval "$(rbenv init -)"

On newer setups, rbenv init usually adds the shims path for you. After configuration, check:

which ruby
ruby -v
rbenv which ruby

Expected result:

which ruby
# something like:
# /Users/yourname/.rbenv/shims/ruby

If you still get:

/usr/bin/ruby

then your shell is not using rbenv shims.

Example diagnosis

Consider this example:

rbenv global 1.9.3-p125
ruby -v
which ruby

Here is what happens step by step:

1. rbenv global 1.9.3-p125

   • rbenv writes the selected version into ~/.rbenv/version.
   • This does not automatically force the shell to use that Ruby.

2. ruby -v

   • Your shell searches the directories in PATH from left to right.
   • If /usr/bin comes before ~/.rbenv/shims, the shell runs /usr/bin/ruby.
   • You see the system Ruby version instead of the version managed by rbenv.

3. which ruby

   • This shows the exact executable your shell found.
   • If it prints /usr/bin/ruby, rbenv shims are not active.

4. If is configured correctly:

This concept appears often in real development work:

• Working on old and new Ruby apps

  • One project may need Ruby 2.7, another Ruby 3.2.
  • rbenv lets each project use the correct version.

• Avoiding system Ruby changes

  • macOS ships with a system Ruby that other tools may rely on.
  • Version managers let you install your own Ruby safely.

• Consistent team environments

  • Teams can commit a .ruby-version file so everyone uses the same Ruby.

• CI and deployment setup

  • Build servers often use version managers or similar PATH-based tools.
  • Understanding shims helps when scripts work locally but fail in CI.

• Debugging command conflicts

  • Many tools such as pyenv, nodenv, and asdf use the same idea.
  • Learning this once helps across multiple ecosystems.

In real projects, developers usually combine rbenv with a few practical patterns:

Project-specific Ruby with .ruby-version

A codebase often includes:

.ruby-version

Example content:

3.2.2

This lets rbenv automatically switch when you enter the project directory.

Guard checks in setup scripts

Teams often add checks like:

ruby -v
bundle -v
which ruby

This catches environment mistakes early.

Early validation in documentation

Many projects include setup instructions such as:

which ruby
# should be ~/.rbenv/shims/ruby

This is a fast sanity check before installing gems or running the app.

Rehash after installing executables

After installing gems that add commands, developers run:

rbenv rehash

This regenerates shims for executables like:

1. Setting the global version but not initializing rbenv

This is the exact issue behind many cases like this one.

Broken situation:

rbenv global 1.9.3-p125
ruby -v
# still shows system ruby

Why it happens:

• the version is saved
• but the shell is not using rbenv shims

How to avoid it:

export PATH="$HOME/.rbenv/bin:$PATH"
eval "$(rbenv init -)"

Then restart the shell.

2. Checking only rbenv global

Broken assumption:

rbenv global
# correct version shown

This does not prove that ruby is using that version.

Always also check:

which ruby
ruby -v

3. Forgetting that order matters

# Show installed Ruby versions
rbenv versions

# Set default Ruby for your user
rbenv global 3.2.2

# Set Ruby for current project
rbenv local 3.2.2

# Set Ruby only for this terminal session
rbenv shell 3.2.2

# Show active version according to rbenv
rbenv version

# Show the actual ruby command your shell runs
which ruby

# Show the ruby executable rbenv resolves to
rbenv which ruby

# Rebuild shims after installing gem executables
rbenv rehash

Required idea

rbenv only works if your shell uses its shims.

Typical shell setup

export PATH="$HOME/.rbenv/bin:$PATH"
eval "$(rbenv init -)"

Healthy setup signs

which ruby
# ~/.rbenv/shims/ruby

ruby -v
# selected version

Red flag

which ruby

Why does rbenv global change the version but ruby -v does not?

Because rbenv saved the version, but your shell is still running a different ruby executable, usually /usr/bin/ruby.

How do I know if rbenv is working correctly?

Run:

which ruby
ruby -v

If which ruby points to ~/.rbenv/shims/ruby, rbenv is active.

What does rbenv rehash do?

It regenerates shims for Ruby executables provided by installed gems. It does not fix PATH or shell initialization problems.

Why does which ruby show /usr/bin/ruby?

Because your PATH is finding the system Ruby before the rbenv shims directory.

Do I need both rbenv and ?

• PATH environment variable — rbenv depends on command lookup order in the shell.
• Shell configuration files — files like .bashrc, .bash_profile, and .zshrc control environment setup.
• Command shims — the core mechanism rbenv uses to redirect commands.
• System Ruby vs managed Ruby — important for understanding why /usr/bin/ruby may still appear.
• ruby-build — commonly used with rbenv to install Ruby versions.
• .ruby-version — allows per-project Ruby version selection.
• Version managers — tools like pyenv, nodenv, and asdf use similar ideas.
• Command resolution in the shell — explains how which, type, and interact.