Ruby

There is no AI here. All content is human-authored and tested for accuracy.

Install Ruby with rv

Install rv to manage Ruby versions. Compare to other version managers such as rbenv, rvm, chruby, mise, and asdf. Use rv, a single fast tool for Ruby version management.

Most developers will need to install newer Ruby versions as they are released. And they will maintain applications that use older Ruby versions. For each project you work on, you should use a specific Ruby version and an isolated set of supporting software packages (gems). A version manager makes it easy to switch between Ruby versions. See the article Compare Ruby Version Managers.

For developers who want fast Ruby installs and version management, and only use the Ruby language, I recommend the rv version manager. If you've used uv for Python, rv works the same way for Ruby.

For developers who use multiple languages, for example Rails developers who use both Ruby and Node for JavaScript, the Mise version manager is a better choice because it is fast and handles multiple languages. You can Install Ruby with Mise.

If you are a casual user and won't be switching among Ruby versions, you can use Homebrew to install Ruby directly. See Install Ruby with Homebrew.

Installing Ruby is part of setting up your Mac for development. See the complete Mac setup roadmap.

Before you get started

You'll need a terminal application to install and use Ruby. Apple includes the Mac terminal but I prefer Warp Terminal. Warp is an easy-to-use terminal application, with AI assistance to help you learn and remember terminal commands. Download Warp Terminal now; it's FREE and worth a try.

Why rv?

Ruby development on Mac has traditionally required multiple tools working together: a version manager such as rbenv, rvm, or chruby, a Ruby build tool such as ruby-build or ruby-install, and Bundler for gem management (gems are Ruby software packages). Each tool needs separate installation and configuration.

The tool rv replaces all of these with a single tool (Bundler is separate but can be accessed through rv to set up a Gem lockfile). Here's what makes rv different:

  • Precompiled Ruby installs. The tool rv downloads prebuilt Ruby binaries for your Mac's architecture (Apple M-series or Intel). Installation takes about one second with no compilation needed.
  • Built-in gem management. The tool rv isolates gems per project automatically. Use rv clean-install instead of bundle install to install project dependencies.
  • One-command tool execution. The rvx command runs any gem CLI tool instantly without manual installation, similar to uvx for Python or npx for JavaScript.
  • Automatic version switching. Rv reads .ruby-version and .tool-versions files and switches Ruby versions when you change directories.

Developers behind some of Ruby's most important tools are contributing to the rv project. André Arko is the rv creator and a long-time maintainer of Bundler and RubyGems. Samuel Giddins is on the RubyGems team. Sam Stephenson is the original creator of rbenv. The project is maintained by Spinel, a co-op of Ruby open source maintainers.

Getting help for rv

Rv is useful and reliable, but it is still a new project. It is evolving quickly so the documentation is not complete. Check the work-in-progress PLANS.md file and look for checkmarks next to completed features. You can ask questions in discussions on GitHub, the #rv channel in the Bundler Slack, and the Spinel Discord.

Install rv

The easiest way to install rv on a Mac is with Homebrew. If you don't have Homebrew installed, see Install Homebrew.

Install rv with Homebrew

Check that Homebrew is available and ready with brew doctor.

Use Homebrew to install rv:

$ brew install rv

Homebrew will download the rv executable and place it in /opt/homebrew/bin/rv so the shell finds it (if Homebrew is correctly installed, /opt/homebrew/bin/ is on the Mac PATH). Verify the installation:

$ rv --version

You should see the rv version number. Rv is available but you still need to add rv to your shell configuration file to make use of its automatic version switching (see below).

Try rv ruby list to confirm that rv is installed correctly and see available Ruby versions.

If you have Ruby versions installed previously by Homebrew or other version managers, rv will show the locations.

$ rv ruby list
┌───────────────┬──────────────────────────────────────────────┐
│ Version       │ Installed                                    │
├───────────────┼──────────────────────────────────────────────┤
│   ruby-3.2.10 │ [available]                                  │
│   ruby-3.3.10 │ [available]                                  │
│   ruby-3.4.9  │ [available]                                  │
│   ruby-4.0.2  │ ~/.rubies/ruby-4.0.2/bin/ruby                │
│   ruby-4.0.2  │ /opt/homebrew/Cellar/ruby/4.0.2/bin/ruby     │
│ * ruby-4.0.2  │ ~/.local/share/rv/rubies/ruby-4.0.2/bin/ruby │
├───────────────┴──────────────────────────────────────────────┤
│ * Default version is the latest installed                    │
└──────────────────────────────────────────────────────────────┘

Optional install with the rv standalone installer

If you prefer not to use Homebrew, rv provides a shell script installer that downloads the rv binary directly from GitHub:

$ curl --proto '=https' --tlsv1.2 -LsSf https://github.com/spinel-coop/rv/releases/latest/download/rv-installer.sh | sh

The installer places the rv binary in ~/.cargo/bin. Make sure that directory is in your Mac PATH. Homebrew is recommended for most users because it handles updates with brew upgrade.

Set up your shell

After installing rv, you need to add shell integration to your terminal. This enables automatic Ruby version switching when you enter a project directory, and adds tab completion for rv commands.

To see the setup instructions for your shell, run rv shell followed by your shell name (zsh is the default on macOS):

$ rv shell zsh
Install rv's shell integration into zsh by running the commands below,
or configuring your shell to do the equivalent.

echo 'eval "$(/opt/homebrew/bin/rv shell init zsh)"' >> ~/.zshrc
echo 'eval "$(/opt/homebrew/bin/rv shell completions zsh)"' >> ~/.zshrc

For shells other than the macOS default Zsh, run rv shell bash, rv shell fish, rv shell nu, or rv shell powershell to see the specific setup instructions for each.

This prints the exact lines you need to add to your shell configuration file. For zsh (the default shell on Mac), you need to add these lines to your ~/.zshrc file. See Mac Shell Configuration for instructions on editing the file. Add:

### ~/.zshrc
# enable rv
eval "$(/opt/homebrew/bin/rv shell init zsh)"
eval "$(/opt/homebrew/bin/rv shell completions zsh)"

The first command provides automatic version switching (rv checks for .ruby-version or .tool-versions before each command and adjusts your environment). The second command helps your terminal suggest commands when you press tab.

Save the file. Close and reopen the terminal application window for the changes to take effect. Alternatively, update your current session:

$ source ~/.zshrc

Verify that rv is working:

$ rv --version

Install Ruby

Install the latest Ruby version using rv:

$ rv ruby install latest

Or specify a version number:

$ rv ruby install 4.0.2

You can also use a partial version like rv ruby install 4.0 to get the latest patch release in a series. If you omit the version entirely, rv looks for a .ruby-version or .tool-versions file in your project directory and installs that version.

The tool rv downloads a precompiled Ruby binary for your Mac's architecture. On Apple Silicon (M-series), this takes about one second. On Intel Macs, rv also provides precompiled binaries, so no compilation is required on either architecture.

Verify that Ruby is installed:

$ ruby -v
ruby 4.0.2 (2026-01-13 revision ...)

Check the path to confirm the rv Ruby is available:

$ which ruby

The path should point to a location inside ~/.local/share/rv/rubies, not /usr/bin/ruby.

If you see an older version (like Ruby 2.6.10), it's the macOS system Ruby. You likely need to close and reopen your terminal so the shell picks up rv's configuration.

You can install additional Ruby versions side by side. For example, if a project requires Ruby 3.4:

$ rv ruby install 3.4.8

Rv can show you all available Ruby versions:

$ rv ruby list --all

Rv supports Ruby versions 3.2 through 4.0.

Use rv

As a project-oriented version manager, rv lets you switch among Ruby projects that use different Ruby versions and resolves gem dependencies without conflicts. Rv handles four core workflows: managing project package dependencies (gems) installing and switching among Ruby versions, running Ruby scripts and commands, and using gem command line tools.

1. Managing project gems

Installing gems (project dependencies) is a first step when you start work with a project. If you're not using rv, you would run bundle install inside the project directory. See Check Ruby Gems and Bundler for background.

When the project has a Gemfile.lock

For any project that already has a Gemfile.lock file, rv provides rv clean-install command to use instead of bundle install . The "clean" means "from a clean slate," installing exactly the gems your project needs without interfering with global system gems.

# Install project gems from lockfile (like bundle install --frozen)
$ rv clean-install

# Short form
$ rv ci

When you try it, you'll see it is very fast.

Use rv ci after cloning a project. The tool reads your project's Gemfile.lock and installs gems with per-project isolation, so different projects can use different gem versions without conflicts, switching automatically as you change project directories.

For a new project without Gemfile.lock

For a new project that doesn't yet have a Gemfile.lock, you need to generate the lockfile once before using rv ci. Bundler is needed to create a Gemfile.lock, but you don't need to install Bundler separately because rv will download and run it for you.

$ rv run bundle lock

After the creation of the Gemfile.lock file, rv ci can handle all subsequent gem dependency management.

2. Pinning Ruby versions

# Install a Ruby version
$ rv ruby install 4.0.2

# Pin a project to use a specific Ruby version
$ rv ruby pin 4.0.2

The rv ruby pin command writes a .ruby-version file in your current directory. When you enter that directory, rv automatically switches to the pinned version. Note that pin does not install the version. Run rv ruby install first if the pinned version is not yet installed.

Rv version management is compatible with the .ruby-version and .tool-versions files used by rbenv, chruby, asdf, and mise, so your existing project files will work with rv.

3. Running Ruby scripts and commands

Use rv run to run any Ruby command with the correct Ruby version:

$ rv run ruby myscript.rb
$ rv run irb

The rv run command ensures the correct Ruby version and gem environment are active for your project. If the needed Ruby version is not installed, rv installs it automatically before running the command.

You can also make Ruby scripts directly executable from the command line by adding this shebang line to the top of any script:

#!/usr/bin/env rv run ruby

Then mark the file as executable with chmod +x myscript.rb. After that, you can run the script directly with ./myscript.rb instead of typing ruby ./myscript.rb.

4. Using gem CLI tools

The rvx command runs any gem's CLI tool instantly, installing the gem automatically if needed. This is the Ruby equivalent of uvx for Python or npx for Node.js.

# Run the latest version of rubocop
$ rvx rubocop

# Run a specific version
$ rvx [email protected]

# Run Rails generators
$ rvx rails new myapp

If you want to install a gem CLI tool permanently (rather than running it on demand), use rv tool install:

# Install a tool in an isolated environment
$ rv tool install rubocop

# Run an installed tool
$ rv tool run rubocop

# List installed tools
$ rv tool list

# Remove a tool you no longer need
$ rv tool uninstall rubocop

Each tool installed with rv tool install gets its own isolated Ruby and gem environment, preventing version conflicts between tools.

Switching from another version manager

If you're currently using a different Ruby version manager, remove it before setting up rv. Running two version managers simultaneously will cause conflicts.

From chruby

Remove the chruby shell configuration lines from your ~/.zshrc file (the lines starting with source /opt/homebrew/share/chruby/ on Apple Silicon or source /usr/local/share/chruby/ on Intel), then uninstall chruby and ruby-install:

$ brew uninstall chruby ruby-install

From rbenv

Remove the rbenv shell configuration line from your ~/.zshrc file (the line containing rbenv init), then uninstall rbenv and ruby-build:

$ brew uninstall rbenv ruby-build

From asdf

If you use asdf only for Ruby, you can remove the Ruby plugin:

$ asdf plugin remove ruby

If you use asdf for other languages too (Node, Python), just remove the Ruby plugin and keep asdf. Otherwise, see Uninstall Asdf for full removal instructions.

From RVM

RVM should be fully removed before installing rv. For RVM, run rvm implode and remove any RVM-related lines from your shell configuration files.

$ rvm implode

After removing your old version manager, install rv and reinstall your Ruby versions using rv ruby install. See Uninstall Ruby for more details on removing Ruby versions installed by other managers.

Troubleshooting

rv: command not found

If you see zsh: command not found: rv after installation, Homebrew's bin directory may not be in your Mac PATH. Check that /opt/homebrew/bin (Apple Silicon) or /usr/local/bin (Intel) is in your path:

$ echo $PATH

If Homebrew's directory is missing, see Install Homebrew on Mac for path configuration.

Conflicts with other version managers

If you see unexpected Ruby version behavior, check your ~/.zshrc for configuration lines from other version managers. Leftover shell initialization from chruby, rbenv, RVM, or other tools can conflict with rv. Remove those lines, then close and reopen the terminal application. See the "Switching from another version manager" section above.

Ruby version not switching

If ruby -v still shows the system Ruby after installing with rv, check these steps:

  1. Make sure you closed and reopened your terminal after adding eval "$(rv shell init zsh)" to ~/.zshrc.
  2. Verify the shell init line is in your ~/.zshrc file: grep "rv shell" ~/.zshrc.
  3. Make sure no other version manager (chruby, rbenv, asdf) is also configured in ~/.zshrc. Only one version manager should be active.

For general Ruby installation troubleshooting, see Troubleshoot Ruby Installation.

Native extension compilation fails

Some gems require native extensions (C code that must be compiled). If gem installation fails with compilation errors, make sure the Xcode Command Line Tools are installed:

$ xcode-select --install

See Install Xcode Command Line Tools for details.

Intel Mac support

The tool rv supports both Apple Silicon (M-series) and Intel Macs. The same commands work on either architecture. Only the Homebrew prefix differs (/usr/local on Intel instead of /opt/homebrew on Apple Silicon).

Update rv

If you installed rv with Homebrew, update it with:

$ brew upgrade rv

If you used the standalone installer, rv can update itself:

$ rv selfupdate

Uninstall rv

If you decide to stop using rv, remove it and clean up your shell configuration.

To remove cached downloads before uninstalling:

$ rv cache clean

Remove the configuration lines from your ~/.zshrc file.

Then uninstall rv with Homebrew:

$ brew uninstall rv

This removes the rv binary.

Then delete the rv data directories to remove installed Ruby versions:

$ rm -rf ~/.local/share/rv ~/.cache/rv

Continue setting up your Mac

Don't miss the full visual roadmap and checklist that shows how to set up a Mac for software development, with all the essential tools and settings you might not yet know about.