Repository files navigation

rbenv is a version manager tool for the Ruby programming language on Unix-like systems. It is useful for switching between multiple Ruby versions on the same machine and for ensuring that each project you are working on always runs on the correct Ruby version.

After rbenv injects itself into your PATH at installation time, any invocation ofruby,gem,bundler, or other Ruby-related executable will first activate rbenv. Then, rbenv scans the current project directory for a file named.ruby-version. If found, that file determines the version of Ruby that should be used within that directory. Finally, rbenv looks up that Ruby version among those installed under~/.rbenv/versions/.

You can choose the Ruby version for your project with, for example:

cd myproject# choose Ruby version 3.1.2:rbenvlocal 3.1.2

Doing so will create or update the.ruby-version file in the current directory with the version that you've chosen. A different project of yours that is another directory might be using a different version of Ruby altogether—rbenv will seamlessly transition from one Ruby version to another when you switch projects.

Finally, almost every aspect of rbenv's mechanism iscustomizable via plugins written in bash.

The simplicity of rbenv has its benefits, but also some downsides. See thecomparison of version managers for more details and some alternatives.

On systems with Homebrew package manager, the “Using Package Managers” method is recommended. On other systems, “Basic Git Checkout” might be the easiest way of ensuring that you are always installing the latest version of rbenv.

1. Install rbenv using one of the following approaches.

   Homebrew

   On macOS or Linux, we recommend installing rbenv withHomebrew.

   brew install rbenv

   Debian, Ubuntu, and their derivatives

   [!CAUTION]
   The version of rbenv that is packaged and maintained in officialDebian and Ubuntu repositories isout of date. To install the latestversion, it is recommended toinstall rbenv using git.

   sudo apt install rbenv

   Arch Linux and its derivatives

   Archlinux has anAUR Package forrbenv and you can install it from the AUR using the instructions from thiswiki page.

   Fedora

   Fedora has anofficial package which you can install:

   sudo dnf install rbenv

2. Set up your shell to load rbenv.

   rbenv init

3. Close your Terminal window and open a new one so your changes take effect.

That's it! You are now ready toinstall some Ruby versions.

This will get you going with the latest version of rbenv without needing a system-wide install.

1. Clone rbenv into~/.rbenv.

   git clone https://github.com/rbenv/rbenv.git~/.rbenv

2. Set up your shell to load rbenv.

   ~/.rbenv/bin/rbenv init

   If you are curious, see here tounderstand whatinit does.

3. Restart your shell so that these changes take effect. (Opening a new terminal tab will usually do it.)

Whenmanually installing rbenv, it might be useful to note how completion scripts for various shells work. Completion scripts help with typing rbenv commands by expanding partially entered rbenv command names and option flags; typically this is invoked by pressingTab key in an interactive shell.

• Thebash completion script for rbenv ships with the project and getsloaded by therbenv init mechanism.

• Thezsh completion script ships with the project, but needs to be added to FPATH in zsh before it can be discovered by the shell. One way to do this would be to edit~/.zshrc:

  # assuming that rbenv was installed to `~/.rbenv`FPATH=~/.rbenv/completions:"$FPATH"autoload -U compinitcompinit

• Thefish completion script for rbenv ships with the fish shell itself and is not maintained by the rbenv project.

Therbenv install command does not ship with rbenv out-of-the-box, but is provided by theruby-build plugin.

Before attempting to install Ruby,check thatyour build environment has the necessary tools and libraries. Then:

# list latest stable versions:rbenv install -l# list all local versions:rbenv install -L# install a Ruby version:rbenv install 3.1.2

For troubleshootingBUILD FAILED scenarios, check theruby-build Discussions section.

git clone https://github.com/rbenv/ruby-build.git"$(rbenv root)"/plugins/ruby-build

Set a Ruby version to finish installation and start using Ruby:

rbenv global 3.1.2# set the default Ruby version for this machine# or:rbenvlocal 3.1.2# set the Ruby version for this directory

Alternatively to therbenv install command, you can download and compile Ruby manually as a subdirectory of~/.rbenv/versions. An entry in that directory can also be a symlink to a Ruby version installed elsewhere on the filesystem.

Select a Ruby version for your project usingrbenv local 3.1.2, for example. Then, proceed to install gems as you normally would:

gem install bundler

Check the location where gems are being installed withgem env:

gem env home# => ~/.rbenv/versions/<version>/lib/ruby/gems/...

As time goes on, Ruby versions you install will accumulate in your~/.rbenv/versions directory.

To remove old Ruby versions, simplyrm -rf the directory of theversion you want to remove. You can find the directory of a particularRuby version with therbenv prefix command, e.g.rbenv prefix 2.7.0.

Theruby-build plugin provides anrbenv uninstall command toautomate the removal process.

The main rbenv commands you need to know are:

Lists all Ruby versions known to rbenv, and shows an asterisk next tothe currently active version.

$ rbenv versions  1.8.7-p352  1.9.2-p290* 1.9.3-p327 (set by /Users/sam/.rbenv/version)  jruby-1.7.1  rbx-1.2.4  ree-1.8.7-2011.03

Displays the currently active Ruby version, along with information onhow it was set.

$ rbenv version1.9.3-p327 (set by /Users/sam/.rbenv/version)

Sets a local application-specific Ruby version by writing the versionname to a.ruby-version file in the current directory. This versionoverrides the global version, and can be overridden itself by settingtheRBENV_VERSION environment variable or with therbenv shellcommand.

rbenv local 3.1.2

When run without a version number,rbenv local reports the currentlyconfigured local version. You can also unset the local version:

rbenv local --unset

Sets the global version of Ruby to be used in all shells by writingthe version name to the~/.rbenv/version file. This version can beoverridden by an application-specific.ruby-version file, or bysetting theRBENV_VERSION environment variable.

rbenv global 3.1.2

The special version namesystem tells rbenv to use the system Ruby(detected by searching your$PATH).

When run without a version number,rbenv global reports thecurrently configured global version.

Sets a shell-specific Ruby version by setting theRBENV_VERSIONenvironment variable in your shell. This version overridesapplication-specific versions and the global version.

rbenv shell jruby-1.7.1

When run without a version number,rbenv shell reports the currentvalue ofRBENV_VERSION. You can also unset the shell version:

rbenv shell --unset

Note that you'll need rbenv's shell integration enabled (step 3 ofthe installation instructions) in order to use this command. If youprefer not to use shell integration, you may simply set theRBENV_VERSION variable yourself:

export RBENV_VERSION=jruby-1.7.1

Installs shims for all Ruby executables known to rbenv (~/.rbenv/versions/*/bin/*). Typically you do not need to run this command, as it will run automatically after installing gems.

rbenv rehash

Displays the full path to the executable that rbenv will invoke whenyou run the given command.

$ rbenv which irb/Users/sam/.rbenv/versions/1.9.3-p327/bin/irb

Lists all Ruby versions that contain the specified executable name.

$ rbenv whence rackup1.9.3-p327jruby-1.7.1ree-1.8.7-2011.03

You can affect how rbenv operates with the following settings:

rbenv init is a helper command to hook rbenv into a shell. This helper is part of the recommended installation instructions, but optional, as an experienced user can set up the following tasks manually. Therbenv init command has two modes of operation:

1. rbenv init: made for humans, this command edits your shell initialization files on disk to add rbenv to shell startup. (Prior to rbenv 1.3.0, this mode only printed user instructions to the terminal, but did nothing else.)

2. rbenv init -: made for machines, this command outputs a shell script suitable to be eval'd by the user's shell.

Whenrbenv init is invoked from a bash shell, for example, it will add the following to the user's~/.bashrc or~/.bash_profile:

# Added by `rbenv init` on <DATE>eval"$(rbenv init - --no-rehash bash)"

You may add this line to your shell initialization files manually if you want to avoid runningrbenv init as part of the setup process. Here is what the eval'd script does:

0. Addsrbenv executable to PATH if necessary.

1. Prepends~/.rbenv/shims directory to PATH. This is basically the only requirement for rbenv to function properly.

2. Installs bash shell completion for rbenv commands.

3. Regenerates rbenv shims. If this step slows down your shell startup, you can invokerbenv init - with the--no-rehash flag.

4. Installs the "sh" dispatcher. This bit is also optional, but allows rbenv and plugins to change variables in your current shell, making commands likerbenv shell possible.

The simplicity of rbenv makes it easy to temporarily disable it, oruninstall from the system.

1. Todisable rbenv managing your Ruby versions, simply comment or remove therbenv init line from your shell startup configuration. This will remove rbenv shims directory from PATH, and future invocations likeruby will execute the system Ruby version, bypassing rbenv completely.

   While disabled,rbenv will still be accessible on the command line, but your Ruby apps won't be affected by version switching.

2. To completelyuninstall rbenv, perform step (1) and then remove the rbenv root directory. This willdelete all Ruby versions that were installed under`rbenv root`/versions/:

   rm -rf "$(rbenv root)"

   If you've installed rbenv using a package manager, as a final stepperform the rbenv package removal:

   • Homebrew:brew uninstall rbenv
   • Debian, Ubuntu, and their derivatives:sudo apt purge rbenv
   • Archlinux and its derivatives:sudo pacman -R rbenv

Tests are executed usingBats:

$ bats test$ bats test/<file>.bats

Please feel free to submit pull requests and file bugs on theissuetracker.