Groom your app’s Ruby environment with rbenv.
- Rbenv Shims In Path Not Found
- Checking For Rbenv Shims In Path Not Found
- Checking For Rbenv Shims In Path Not Found Mac
Rbenv is supported on Linux and Mac OS X. Rbenv doesn’t work on Windows (and isn’t really necessary on Windows as there is no system Ruby on Windows). On Windows, the RubyInstaller and/or Pik are both good alternatives to work with multiple versions of Ruby on the same box. Rbenv is a new lightweight Ruby version management tool built by Sam Stephenson (of 37signals and Prototype.js fame). The established leader in the Ruby version management scene is RVM but rbenv is an interesting alternative if you want or need something significantly lighter with fewer features. Think of it as a bit like Sinatra and Rails. It's not about which is the best, it's about which.
Use rbenv to pick a Ruby version for your application and guaranteethat your development environment matches production. Put rbenv to workwith Bundler 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. No headaches running apps on different versions of Ruby. Just Works™ from the command line and with app servers like Pow. Override the Ruby version anytime: just set an environment variable.
Rock-solid in production. Your application's executables are its interface with ops. With rbenv and Bundler binstubs you'll never again need to
cd
in a cron job or Chef recipe to ensure you've selected the right runtime. The Ruby version dependency lives in one place—your app—so upgrades and rollbacks are atomic, even when you switch versions.One thing well. rbenv is concerned solely with switching Ruby versions. It's simple and predictable. A rich plugin ecosystem lets you tailor it to suit your needs. Compile your own Ruby versions, or use the ruby-build plugin to automate the process. Specify per-application environment variables with rbenv-vars. See more plugins on the wiki.
Table of Contents
- How It Works
- Installation
- Command Reference
How It Works
At a high level, rbenv intercepts Ruby commands using shimexecutables injected into your
PATH
, determines which Ruby versionhas been specified by your application, and passes your commands alongto the correct Ruby installation.Understanding PATH
When you run a command like
ruby
or rake
, your operating systemsearches through a list of directories to find an executable file withthat name. This list of directories lives in an environment variablecalled PATH
, with each directory in the list separated by a colon:Directories in
PATH
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
.Understanding Shims
rbenv works by inserting a directory of shims at the front of your
PATH
:Through a process called rehashing, 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 your
PATH
for an executable file namedrake
- Find the rbenv shim named
rake
at the beginning of yourPATH
- Run the shim named
rake
, which in turn passes the command along torbenv
Choosing the Ruby Version
When you execute a shim, rbenv determines which Ruby version to use byreading it from the following sources, in this order:
- The
RBENV_VERSION
environment variable, if specified. You can usetherbenv shell
command to set this environmentvariable in your current shell session. - 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. - 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. - 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.
Locating the Ruby Installation
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
.Installation
Compatibility note: rbenv is incompatible with RVM. Please make sure to fully uninstall RVM and remove any references to it from your shell initialization files before installing rbenv.
Homebrew on macOS
If you're on macOS, we recommend installing rbenv withHomebrew.
- Install rbenv.
Note that this also installs
ruby-build
, so you'll be ready to install other Ruby versions out of the box.- Set up rbenv in your shell.
Follow the printed instructions to set up rbenv shell integration.
- Close your Terminal window and open a new one so your changes takeeffect.
- Verify that rbenv is properly set up using thisrbenv-doctor script:
- That's it! Installing rbenv includes ruby-build, so now you're ready toinstall some other Ruby versions using
rbenv install
.
Upgrading with Homebrew
To upgrade to the latest rbenv and update ruby-build with newly releasedRuby versions, upgrade the Homebrew packages:
Basic GitHub Checkout
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.
- Clone rbenv into
~/.rbenv
.Optionally, try to compile dynamic bash extension to speed up rbenv. Don'tworry if it fails; rbenv will still work normally: - Add
~/.rbenv/bin
to your$PATH
for access to therbenv
command-line utility.
- For bash:
- For Ubuntu Desktop:
- For Zsh:
- For Fish shell:
- Set up rbenv in your shell.
Follow the printed instructions to set up rbenv shell integration.
- Restart your shell so that PATH changes take effect. (Opening a newterminal tab will usually do it.)
- Verify that rbenv is properly set up using thisrbenv-doctor script:
- (Optional) Install ruby-build, which provides the
rbenv install
command that simplifies the process ofinstalling new Ruby versions.
Upgrading with Git
If you've installed rbenv manually using Git, you can upgrade to thelatest version by pulling from GitHub:
Updating the list of available Ruby versions
If you're using the
rbenv install
command, then the list of available Ruby versions is not automatically updated when pulling from the rbenv repo. To do this manually:![Shims Shims](https://i.stack.imgur.com/CMvTK.png)
How rbenv hooks into your shell
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 what rbenv init
actually does:- 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
. - 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. - 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 run
rbenv rehash
manually. - Installs the sh dispatcher. This bit is also optional, but allowsrbenv and plugins to change variables in your current shell, makingcommands like
rbenv 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.
Run
rbenv init -
for yourself to see exactly what happens under thehood.Installing Ruby versions
The
rbenv install
command doesn't ship with rbenv out of the box, butis provided by the ruby-build project. If you installed it eitheras part of GitHub checkout process outlined above or via Homebrew, youshould be able to:Alternatively to the
install
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 the versions/
directory as a separate Ruby version.Installing Ruby gems
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 bychecking
rbenv version
(see Command Reference). Selectanother version using rbenv local 2.0.0-p247
, for example. Then, proceed toinstall gems as you normally would: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 with
gem env
:Uninstalling Ruby versions
As time goes on, Ruby versions you install will accumulate in your
~/.rbenv/versions
directory.To remove old Ruby versions, simply
rm -rf
the directory of theversion you want to remove. You can find the directory of a particularRuby version with the rbenv prefix
command, e.g. rbenv prefix1.8.7-p357
.The ruby-build plugin provides an
rbenv uninstall
command toautomate the removal process.Uninstalling rbenv
The simplicity of rbenv makes it easy to temporarily disable it, oruninstall from the system.
- To disable rbenv managing your Ruby versions, simply remove the
rbenv 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 Ruby apps won't be affected by version switching.- To completely uninstall rbenv, perform step (1) and then removeits root directory. This will delete all Ruby versions that wereinstalled under
`rbenv root`/versions/
directory:
If you've installed rbenv using a package manager, as a final step perform the rbenv package removal. For instance, for Homebrew:
Command Reference
Like
git
, the rbenv
command delegates to subcommands based on itsfirst argument. The most common subcommands are:rbenv local
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 settingthe RBENV_VERSION
environment variable or with the rbenv shell
command.When run without a version number,
rbenv local
reports the currentlyconfigured local version. You can also unset the local version:rbenv global
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 the RBENV_VERSION
environment variable.The special version name
system
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.rbenv shell
Sets a shell-specific Ruby version by setting the
RBENV_VERSION
environment variable in your shell. This version overridesapplication-specific versions and the global version.When run without a version number,
rbenv shell
reports the currentvalue of RBENV_VERSION
. You can also unset the shell version: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 the
RBENV_VERSION
variable yourself:rbenv versions
Lists all Ruby versions known to rbenv, and shows an asterisk next tothe currently active version.
rbenv version
Displays the currently active Ruby version, along with information onhow it was set.
rbenv rehash
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 which
Displays the full path to the executable that rbenv will invoke whenyou run the given command.
rbenv whence
Lists all Ruby versions with the given command installed.
Environment variables
You can affect how rbenv operates with the following settings:
name | default | description |
---|---|---|
RBENV_VERSION | Specifies the Ruby version to be used.Also see rbenv shell | |
RBENV_ROOT | ~/.rbenv | Defines the directory under which Ruby versions and shims reside.Also see rbenv root |
RBENV_DEBUG | Outputs debug information.Also as: rbenv --debug <subcommand> | |
RBENV_HOOK_PATH | see wiki | Colon-separated list of paths searched for rbenv hooks. |
RBENV_DIR | $PWD | Directory to start searching for .ruby-version files. |
Development
The rbenv source code is hosted onGitHub. It's clean, modular,and easy to understand, even if you're not a shell hacker.
Tests are executed using Bats:
Please feel free to submit pull requests and file bugs on the issuetracker.
We recently switched from RVM to rbenv for managing Ruby versions.
“Make each program do one thing well.” - Tenet #2 of The UNIX Philosophy
Why consider switching to rbenv
The UNIX philosophy espouses an approach to software in which small, sharp tools are designed and used to address discrete needs. By this standard, RVM simply does too much. RVM is responsible not only for changing Ruby versions, but for installing rubies and managing gemsets, as well.
Breaking these responsibilities apart and selecting a tool for each job is a good alternative to using RVM. Along with rbenv, we’re using Bundler to manage gems (replacing gemsets) and ruby-build to install rubies.
Rbenv Shims In Path Not Found
How our rbenv workflow works
- Uses ruby-build to install Rubies
- Relies on Bundler and its’ binstubs to manage gems
- Uses shims to handle executable gems
- Updates shims upon receipt of the
rbenv rehash
command after new Ruby executables are installed (rehashing can be automated with the gem rehash plugin) - Installs everything to
~/.rbenv/
How to switch from RVM to rbenv
Check out our laptop script to see our process for installing rbenv, or follow the steps below.
If you’re a tmux user, be sure to kill all your tmux sessions before installing rbenv to prevent RVM from polluting your environment.
In your root directory, remove RVM from your system:
Restart your shell to ensure you’re beginning your rbenv installation in a clean environment:
Next, install rbenv using homebrew:
Configure your bash or zsh profile:
Install ruby-build and rbenv rehash gem using homebrew:
Install your preferred version of Ruby and set it as the global default:
Update to the latest Rubygems version:
Install gems critical to Rails development, e.g.
You can set project-specific Ruby and gem versions by running the
rbenv local
command within your project directory:If you follow the steps above and find you’re having issues with rbenv, check your
echo $PATH
. Most likely you’re not seeing the appropriate ~/.rbenv
dir.Checking For Rbenv Shims In Path Not Found
If so, you either haven’t added the init to your zsh profile, or something else is mangling the path.
Checking For Rbenv Shims In Path Not Found Mac
Extras
- To ease the transition, install the use plugin, which lets you run RVM-style commands with rbenv
- rbenv-binstubs is a handy plugin that allows you to omit
bundle exec
when you run commands