How to Change Ruby Version on Mac

To change Ruby versions on a Mac, use a version manager such as rbenv or RVM. Choose a local version for one project or a global version for your shell. Bundler can check that a project uses its declared Ruby version, but it does not install Ruby or switch versions. The steps below show both managers; choose one and verify that your shell resolves the selected Ruby.

Choose a Ruby version manager for your Mac

Use rbenv if you want a small tool that selects Ruby through your shell’s PATH and can read a project’s .ruby-version file. Use RVM if you prefer a manager that also provides Ruby gemsets and broader environment management. Avoid configuring both to modify the same shell startup files: competing PATH changes can make the active version hard to diagnose.

macOS installations differ, so check what is available with ruby -v before changing anything. Do not assume that every Mac includes Ruby or that a package manager provides a particular “latest” version. A version manager installs the specific version you request; the installed compiler and system libraries may affect which older versions can be built.

Install and switch Ruby with rbenv

Install Homebrew first if it is not already available. Then install rbenv with brew install rbenv. On current Homebrew setups, initialize it in your shell with rbenv init; follow the command’s instructions for your shell and restart the terminal or reload its startup file. Older rbenv setup instructions may use a shell-specific initialization line, so use the instructions for the version you installed.

Install a Ruby release with rbenv install 3.2.2 (replace the example with the version your project needs). If the rbenv install command is unavailable, install the ruby-build component using the method recommended for your rbenv installation, then retry.

Choose how broadly to apply the version:

• In a project directory, run rbenv local 3.2.2. This writes 3.2.2 to that directory’s .ruby-version, so rbenv selects it there and in child directories.
• For your default outside directories with a local setting, run rbenv global 3.2.2.

A local setting takes precedence over the global setting. Check the selected version with rbenv version, then confirm that ruby -v and which ruby resolve the expected interpreter. If ruby still points somewhere else, initialize rbenv in the shell you actually use and check that $(rbenv root)/shims appears before other Ruby locations in PATH.

Install and switch Ruby with RVM

RVM uses a remote installer. Review the RVM project’s installation instructions before running its installer; piping a downloaded script directly into a shell executes code from the network. After installing RVM as documented for your shell, open a new terminal or load its shell integration. A session can load an existing installation with source ~/.rvm/scripts/rvm.

Install the Ruby version required by your project with rvm install 3.2.2, then select it with rvm use 3.2.2. To make that version the default for new shells, use rvm use 3.2.2 --default. In a project directory, rvm use 3.2.2 selects the version for the current shell; RVM also supports project files when its shell integration is configured.

Verify the result with ruby -v and which ruby. If the old version remains active, confirm RVM loaded in the current shell and inspect PATH for another Ruby manager or system Ruby that appears first. RVM and rbenv are separate tools; commands for one do not configure the other.

Use Bundler to require a project Ruby version

A project can declare its required Ruby in its Gemfile:

ruby "3.2.2"

Use the version the project supports. Then run bundle install with that Ruby selected. Bundler checks the current interpreter against the Gemfile requirement and installs the project’s gems; it does not download or switch Ruby. If the active Ruby does not satisfy the requirement, select or install a compatible Ruby with rbenv or RVM, then run Bundler again.

A committed .ruby-version file can help a version manager select the project’s Ruby automatically. Keep it aligned with the Gemfile requirement, and make sure the required version is installed for each developer or build environment.

Verify the active Ruby version and resolve common issues

Run these commands from the same terminal and directory where you run your application:

• ruby -v prints the version of the interpreter the shell runs.
• which ruby shows the executable found first on PATH.
• rbenv version reports the selected version and its source when using rbenv.
• rvm current reports the active version when using RVM.

This small Ruby example prints the version reported by the interpreter that runs it. The supplied run printed:

puts "Active Ruby: #{RUBY_VERSION}"

Active Ruby: 3.1.2

If a manager reports the intended version but ruby -v does not, the shell is probably resolving a different executable. Check that the manager’s initialization is in the startup file for your active shell, open a fresh terminal, and inspect PATH again. Also check the current directory for .ruby-version, which can override rbenv’s global selection. When Bundler reports a Ruby requirement mismatch, compare the Gemfile requirement with ruby -v; changing gems alone will not resolve a Ruby interpreter mismatch.

FAQ

Can I install more than one Ruby version?

Yes. Both rbenv and RVM can keep multiple Ruby versions installed. Select the appropriate one globally or for a project rather than removing a version that another project may use.

How do I use a different Ruby version for just one project?

With rbenv, run rbenv local VERSION in the project directory; it records the selection in .ruby-version. With RVM, select the version in the project shell with rvm use VERSION, and configure RVM’s project-file support if you want automatic selection when entering the directory. In either case, ensure the version is installed and verify it with ruby -v.

Do I need to uninstall the previous Ruby version?

No. Keep versions that other projects need. If you later remove one, use the removal command for the manager that installed it, and first check that no project depends on it.

Does Bundler change the active Ruby version?

No. A ruby declaration in the Gemfile lets Bundler check whether the active interpreter meets the project requirement. Use a version manager to install and select Ruby, then run bundle install.