Repository files navigation

Use rbenv to pick a Ruby version for your application and guaranteethat your development environment matches production. Put rbenv to workwithBundler for painless Ruby upgrades andbulletproof deployments.

Powerful in development. Specify your app's Ruby version once,in a single file. Keep all your teammates on the same page. Noheadaches running apps on different versions of Ruby. Just Works™from the command line and with app servers likePow.Override the Ruby version anytime: just set an environment variable.

Rock-solid in production. Your application's executables are itsinterface with ops. With rbenv andBundlerbinstubsyou'll never again need tocd in a cron job or Chef recipe toensure you've selected the right runtime. The Ruby versiondependency lives in one place—your app—so upgrades and rollbacks areatomic, even when you switch versions.

One thing well. rbenv is concerned solely with switching Rubyversions. It's simple and predictable. A rich plugin ecosystem letsyou tailor it to suit your needs. Compile your own Ruby versions, oruse theruby-buildplugin to automate the process. Specify per-application environmentvariables withrbenv-vars.See moreplugins on thewiki.

Why choose rbenv overRVM?

• How It Works
  • Understanding PATH
  • Understanding Shims
  • Choosing the Ruby Version
  • Locating the Ruby Installation
• Installation
  • Homebrew on macOS
    • Upgrading with Homebrew
  • Basic GitHub Checkout
    • Upgrading with Git
    • Updating the list of available Ruby versions
  • How rbenv hooks into your shell
  • Installing Ruby versions
    • Installing Ruby gems
  • Uninstalling Ruby versions
  • Uninstalling rbenv
• Command Reference
  • rbenv local
  • rbenv global
  • rbenv shell
  • rbenv versions
  • rbenv version
  • rbenv rehash
  • rbenv which
  • rbenv whence
• Environment variables
• Development

At a high level, rbenv intercepts Ruby commands using shimexecutables injected into yourPATH, determines which Ruby versionhas been specified by your application, and passes your commands alongto the correct Ruby installation.

When you run a command likeruby orrake, your operating systemsearches through a list of directories to find an executable file withthat name. This list of directories lives in an environment variablecalledPATH, with each directory in the list separated by a colon:

/usr/local/bin:/usr/bin:/bin

Directories inPATH are searched from left to right, so a matchingexecutable in a directory at the beginning of the list takesprecedence over another one at the end. In this example, the/usr/local/bin directory will be searched first, then/usr/bin,then/bin.

rbenv works by inserting a directory ofshims at the front of yourPATH:

~/.rbenv/shims:/usr/local/bin:/usr/bin:/bin

Through a process calledrehashing, rbenv maintains shims in thatdirectory to match every Ruby command across every installed versionof Ruby—irb,gem,rake,rails,ruby, and so on.

Shims are lightweight executables that simply pass your command alongto rbenv. So with rbenv installed, when you run, say,rake, youroperating system will do the following:

• Search yourPATH for an executable file namedrake
• Find the rbenv shim namedrake at the beginning of yourPATH
• Run the shim namedrake, which in turn passes the command along torbenv

When you execute a shim, rbenv determines which Ruby version to use byreading it from the following sources, in this order:

1. TheRBENV_VERSION environment variable, if specified. You can usetherbenv shell command to set this environmentvariable in your current shell session.

2. The first.ruby-version file found by searching the directory of thescript you are executing and each of its parent directories until reachingthe root of your filesystem.

3. The first.ruby-version file found by searching the current workingdirectory and each of its parent directories until reaching the root of yourfilesystem. You can modify the.ruby-version file in the current workingdirectory with therbenv local command.

4. The global~/.rbenv/version file. You can modify this file usingtherbenv global command. If the global versionfile is not present, rbenv assumes you want to use the "system"Ruby—i.e. whatever version would be run if rbenv weren't in yourpath.

Once rbenv has determined which version of Ruby your application hasspecified, it passes the command along to the corresponding Rubyinstallation.

Each Ruby version is installed into its own directory under~/.rbenv/versions. For example, you might have these versionsinstalled:

• ~/.rbenv/versions/1.8.7-p371/
• ~/.rbenv/versions/1.9.3-p327/
• ~/.rbenv/versions/jruby-1.7.1/

Version names to rbenv are simply the names of the directories in~/.rbenv/versions.

Compatibility note: rbenv isincompatible with RVM. Please makesure to fully uninstall RVM and remove any references to it fromyour shell initialization files before installing rbenv.

If you're on macOS, we recommend installing rbenv withHomebrew.

1. Install rbenv.

   $ brew install rbenv

   Note that this also installsruby-build, so you'll be ready toinstall other Ruby versions out of the box.

2. Set up rbenv in your shell.

   $ rbenv init

   Follow the printed instructions toset up rbenv shell integration.

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

4. Verify that rbenv is properly set up using thisrbenv-doctor script:

   $ curl -fsSL https://github.com/rbenv/rbenv-installer/raw/master/bin/rbenv-doctor| bashCheckingfor`rbenv'in PATH: /usr/local/bin/rbenvCheckingforrbenv shimsin PATH: OKChecking`rbenv install' support: /usr/local/bin/rbenv-install (ruby-build 20170523)Counting installed Ruby versions: none  There aren't any Ruby versions installed under`~/.rbenv/versions'.  You can install Ruby versions like so: rbenv install 2.2.4Checking RubyGems settings: OKAuditing installed plugins: OK

5. That's it! Installing rbenv includes ruby-build, so now you're ready toinstall some other Ruby versions usingrbenv install.

To upgrade to the latest rbenv and update ruby-build with newly releasedRuby versions, upgrade the Homebrew packages:

$ brew upgrade rbenv ruby-build

For a more automated install, you can userbenv-installer.If you prefer a manual approach, follow the steps below.

This will get you going with the latest version of rbenv without needinga systemwide install.

1. Clone rbenv into~/.rbenv.

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

   Optionally, try to compile dynamic bash extension to speed up rbenv. Don'tworry if it fails; rbenv will still work normally:

   $ cd ~/.rbenv && src/configure && make -C src

2. Add~/.rbenv/bin to your$PATH for access to therbenvcommand-line utility.

   • Forbash:

     $echo'export PATH="$HOME/.rbenv/bin:$PATH"'>>~/.bash_profile

   • ForUbuntu Desktop:

     $echo'export PATH="$HOME/.rbenv/bin:$PATH"'>>~/.bashrc

   • ForZsh:

     $echo'export PATH="$HOME/.rbenv/bin:$PATH"'>>~/.zshrc

   • ForFish shell:

     $set-Ux fish_user_paths$HOME/.rbenv/bin$fish_user_paths

3. Set up rbenv in your shell.

   $~/.rbenv/bin/rbenv init

   Follow the printed instructions toset up rbenv shell integration.

4. Restart your shell so that PATH changes take effect. (Opening a newterminal tab will usually do it.)

5. Verify that rbenv is properly set up using thisrbenv-doctor script:

   $ curl -fsSL https://github.com/rbenv/rbenv-installer/raw/master/bin/rbenv-doctor| bashCheckingfor`rbenv'in PATH: /usr/local/bin/rbenvCheckingforrbenv shimsin PATH: OKChecking`rbenv install' support: /usr/local/bin/rbenv-install (ruby-build 20170523)Counting installed Ruby versions: none  There aren't any Ruby versions installed under`~/.rbenv/versions'.  You can install Ruby versions like so: rbenv install 2.2.4Checking RubyGems settings: OKAuditing installed plugins: OK

6. (Optional) Installruby-build, which provides therbenv install command that simplifies the process ofinstalling new Ruby versions.

If you've installed rbenv manually using Git, you can upgrade to thelatest version by pulling from GitHub:

$cd~/.rbenv$ git pull

If you're using therbenv install command, then the list of available Ruby versions is not automatically updated when pulling from the rbenv repo. To do this manually:

$cd~/.rbenv/plugins/ruby-build$ git pull

Skip this section unless you must know what every line in your shellprofile is doing.

rbenv init is the only command that crosses the line of loadingextra commands into your shell. Coming from RVM, some of you might beopposed to this idea. Here's whatrbenv init actually does:

1. Sets up your shims path. This is the only requirement for rbenv tofunction properly. You can do this by hand by prepending~/.rbenv/shims to your$PATH.

2. Installs autocompletion. This is entirely optional but prettyuseful. Sourcing~/.rbenv/completions/rbenv.bash will set thatup. There is also a~/.rbenv/completions/rbenv.zsh for Zshusers.

3. Rehashes shims. From time to time you'll need to rebuild yourshim files. Doing this automatically makes sure everything is up todate. You can always runrbenv rehash manually.

4. Installs the sh dispatcher. This bit is also optional, but allowsrbenv and plugins to change variables in your current shell, makingcommands likerbenv shell possible. The sh dispatcher doesn't doanything invasive like overridecd or hack your shell prompt, but iffor some reason you needrbenv to be a real script rather than ashell function, you can safely skip it.

Runrbenv init - for yourself to see exactly what happens under thehood.

Therbenv install command doesn't ship with rbenv out of the box, butis provided by theruby-build project. If you installed it eitheras part of GitHub checkout process outlined above or via Homebrew, youshould be able to:

# list all available versions:$ rbenv install -l# install a Ruby version:$ rbenv install 2.0.0-p247

Alternatively to theinstall command, you can download and compileRuby manually as a subdirectory of~/.rbenv/versions/. An entry inthat directory can also be a symlink to a Ruby version installedelsewhere on the filesystem. rbenv doesn't care; it will simply treatany entry in theversions/ directory as a separate Ruby version.

Once you've installed some Ruby versions, you'll want to install gems.First, ensure that the target version for your project is the one you want bycheckingrbenv version (seeCommand Reference). Selectanother version usingrbenv local 2.0.0-p247, for example. Then, proceed toinstall gems as you normally would:

$ gem install bundler

You don't need sudo to install gems. Typically, the Ruby versions will beinstalled and writeable by your user. No extra privileges are required toinstall gems.

Check the location where gems are being installed withgem env:

$ gem env home# => ~/.rbenv/versions/<ruby-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 1.8.7-p357.

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

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

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

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

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

    rm -rf `rbenv root`

   If you've installed rbenv using a package manager, as a final stepperform the rbenv package removal. For instance, for Homebrew:

    brew uninstall rbenv

Likegit, therbenv command delegates to subcommands based on itsfirst argument. The most common subcommands are:

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 1.9.3-p327

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 1.8.7-p352

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

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)

Installs shims for all Ruby executables known to rbenv (i.e.,~/.rbenv/versions/*/bin/*). Run this command after you install a newversion of Ruby, or install a gem that provides commands.

$ 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 with the given command installed.

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

You can affect how rbenv operates with the following settings:

The rbenv source code ishosted onGitHub. It's clean, modular,and easy to understand, even if you're not a shell hacker.

Tests are executed usingBats:

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

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