Guide · Open source

How to use rbenv: install, set Ruby versions per project

Updated 2026-10-29 · written with AI from the project's own documentation and checked against our catalogue data

rbenv is a version manager for the Ruby programming language on Unix-like systems such as macOS and Linux. It keeps several Ruby versions installed on one machine and switches to the right one for each project based on a .ruby-version file. This guide shows you how to install rbenv, set your shell up, install Ruby versions and choose which version each project uses.

rbenvrbenv/rbenv · ★ 16.7k · MIT Install options & downloads

Quick start

1Install rbenv. On macOS or Linux, run brew install rbenv with Homebrew. Use a git checkout into ~/.rbenv if you do not use Homebrew.
2Run rbenv init. Run rbenv init to set up your shell to load rbenv, then open a new terminal window.
3Install ruby-build. rbenv install comes from the ruby-build plugin. Check that your build tools are present, then confirm the command works with rbenv install -l.
4Install a Ruby version. Run rbenv install followed by a version number, such as 3.1.2.
5Set the version for a project. Go to your project folder and run rbenv local with the version number. This creates a .ruby-version file.
6Check the active version. Run rbenv version to confirm which Ruby version is active and how it was set.

What rbenv does and how it picks a Ruby version

After rbenv is installed, it injects itself into your PATH. When you run ruby, gem, bundler or another Ruby-related executable, rbenv activates first and scans the current project directory for a file named .ruby-version. If it finds one, that file sets the Ruby version for that directory. rbenv then looks for that version among the versions installed under ~/.rbenv/versions/.

When you move to a different project that uses another Ruby version, rbenv switches versions automatically.

Install rbenv on macOS or Linux

On macOS or Linux, the README recommends installing rbenv with Homebrew. Other systems have packages for Debian, Ubuntu, Arch Linux, Fedora and openSUSE Tumbleweed, but the README warns that the Debian and Ubuntu package is out of date. For the latest version without a system-wide install, use a git checkout into ~/.rbenv.

Homebrew (recommended on macOS or Linux): install with the command shown below.
Manual git checkout: clone into ~/.rbenv, then run ~/.rbenv/bin/rbenv init.

brew install rbenv

Set up your shell to load rbenv

Run rbenv init once so your shell loads rbenv. Then close your terminal window and open a new one so the change takes effect. If you installed with git, restart your shell instead, which usually means opening a new terminal tab.

rbenv init

Install a Ruby version

The rbenv install command is not included with rbenv. It is provided by the ruby-build plugin. Before you install Ruby, check that your build environment has the tools and libraries listed in the ruby-build wiki. Then list the versions you can install and install one.

rbenv install -l lists the latest stable versions.
rbenv install -L lists all local versions.
If rbenv install is not found, install ruby-build as a plugin by cloning it into the plugins folder under rbenv root.
For BUILD FAILED errors, check the ruby-build Discussions section on build failures.

# list latest stable versions:
rbenv install -l

# install a Ruby version:
rbenv install 3.1.2

Choose a Ruby version for a project or machine

Use rbenv local inside a project folder to write a .ruby-version file there. Use rbenv global to set the default for all shells, which is stored in ~/.rbenv/version. A .ruby-version file overrides the global version. The RBENV_VERSION environment variable and rbenv shell override both.

Set a version with rbenv global or rbenv local, then install gems as you normally would. Do not use sudo to install gems. If you get a permission error, your system Ruby is probably still the global default, so run rbenv global with the version you want and try again.

rbenv versions shows all known versions and marks the active one with an asterisk.
rbenv version shows the active version and how it was set.
rbenv local --unset removes the local version.
rbenv global system uses the system Ruby found on your PATH.
Check where gems are installed with gem env home.

cd myproject
# choose Ruby version 3.1.2:
rbenv local 3.1.2

Remove old Ruby versions

Installed versions build up in ~/.rbenv/versions over time. To remove one, find its folder with rbenv prefix and delete that folder. The ruby-build plugin also provides an rbenv uninstall command that automates this.

rbenv prefix 2.7.0

What people use it for

Running an older Rails app on the Ruby version it expects while using a newer version for another project.
Committing a .ruby-version file to a repository so every team member uses the same Ruby version.
Installing Ruby versions under your home directory so you do not need sudo to install gems.
Keeping a default global Ruby version for the whole machine and overriding it per project.

Frequently asked questions

Is rbenv free to use?

rbenv is released under the MIT licence, and its source code is public on GitHub. The README does not describe any paid version.

What are the requirements for rbenv?

rbenv runs on Unix-like systems such as macOS and Linux. You need a shell such as bash or zsh, and Homebrew is recommended on macOS or Linux, or git if you use a manual checkout.

Does rbenv work on Windows?

No. The README says rbenv is for Unix-like systems, so Windows users should use a Windows-specific tool instead.

Why does rbenv install say command not found?

The rbenv install command comes from the separate ruby-build plugin, not from rbenv itself. Install ruby-build as a plugin by cloning it into the plugins folder under rbenv root, then try again.

What is the difference between rbenv local and rbenv global?

rbenv local writes a .ruby-version file in the current directory and applies to that project. rbenv global writes to ~/.rbenv/version and sets the default for all shells, and a project .ruby-version file overrides it.

What are the alternatives to rbenv?

The project lists asdf, chruby, RVM and mise as comparable tools. The README notes that rbenv's simplicity has benefits but also some downsides, and it links to a comparison of version managers.

New agent skills, repos and AI tools — every week

The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.

Our verdict

rbenv suits developers on macOS or Linux who work across several Ruby projects and want a small tool they can extend with plugins. It is not a good fit for Windows users, people who only ever use one Ruby version, or anyone who wants rbenv install to work without adding the ruby-build plugin.

Install options & downloads