rbenv

Install a Ruby version

$ rbenv install [version]

$ rbenv install --list

$ rbenv versions

$ rbenv global [version]

$ rbenv local [version]

$ rbenv version

$ rbenv uninstall [version]

$ rbenv whence [executable]

rbenv command [args...]

Common commands include:
rbenv install version
rbenv global version
rbenv local version
rbenv versions
rbenv rehash
rbenv exec command [args...]

install
    Installs a specific Ruby version. Requires the ruby-build plugin.

global
    Sets the global Ruby version to be used for all shells and projects.

local
    Sets a project-specific Ruby version by creating a .ruby-version file in the current directory.

shell
    Sets a shell-specific Ruby version, overriding global and local versions. This setting is temporary.

versions
    Lists all installed Ruby versions and indicates the currently active one.

rehash
    Rebuilds the rbenv shim executables. Must be run after installing new Ruby versions or gems with executables.

exec
    Executes a command with the currently selected Ruby version. Useful for scripts.

which
    Displays the full path to the executable that rbenv will run for a given command.

version
    Displays the currently active Ruby version and its origin (global, local, shell).

version-name
    Displays only the name of the currently active Ruby version.

rbenv is a lightweight Ruby version management tool that allows you to install and switch between multiple versions of Ruby on the same machine. Unlike other managers like RVM, rbenv operates by modifying your PATH environment variable and using "shims"—small executable scripts that intercept commands like ruby, gem, bundle, etc.

When you run a Ruby command, rbenv determines which Ruby version should be used based on a hierarchy of settings (local, global, shell) and executes the command with the correct Ruby interpreter. This approach makes rbenv less intrusive and more transparent, as it doesn't "hijack" your shell. It's particularly useful for development environments where different projects might require different Ruby versions, ensuring dependency isolation and consistency.

rbenv itself does not install Ruby versions; it relies on the ruby-build plugin for this functionality. Users must ensure rbenv rehash is run after installing new Ruby versions or gems that include executable scripts, otherwise the executables might not be found. It does not manage gemsets by default, though plugins are available for this purpose. Unlike RVM, rbenv does not modify your shell environment with 'hooks' or 'cd' command overrides.

rbenv works by inserting its own directory of shims at the front of your PATH. When you run a command like ruby or bundle, your operating system searches PATH from left to right. It finds the rbenv shim first, which then determines the correct Ruby version based on your settings (global, local, shell) and executes the actual Ruby executable from that version's installation directory. This allows for seamless switching without shell "hooks".

After installing rbenv, you typically need to add eval "$(rbenv init -)" to your shell's initialization file (e.g., ~/.bashrc, ~/.zshrc) to enable its functionality, including auto-completion and shims.

rbenv was created by Sam Stephenson, aiming to be a simpler and less invasive alternative to existing Ruby version managers like RVM. Its design philosophy focuses on being unobtrusive, primarily working by manipulating the PATH environment variable and using a system of shims rather than modifying core shell functions. This design choice has made it popular among developers who prefer a more transparent and explicit control over their Ruby environment.

ruby-build(1), rvm(1), chruby(1), bundle(1)