rbenv — Manage Ruby Versions with Ease

Introduction

rbenv provides a clean, minimal way to install and switch between Ruby interpreters on a per-project basis. It works through PATH shims and .ruby-version files, keeping your system Ruby untouched and your environment predictable.

What rbenv Does

• Installs any MRI, JRuby, or TruffleRuby version via the ruby-build plugin
• Sets the active Ruby globally, per-directory, or per-shell session
• Reads .ruby-version files for automatic per-project switching
• Manages shims in ~/.rbenv/shims so the correct binary is always resolved
• Rehashes shims automatically when gems install new executables

Architecture Overview

rbenv places a directory of lightweight shim scripts at the front of PATH. When any Ruby command runs, the shim checks the RBENV_VERSION environment variable, then the closest .ruby-version file, then the global setting to find the matching interpreter under ~/.rbenv/versions/. The ruby-build plugin handles downloading and compiling Ruby from source.

Self-Hosting & Configuration

• Clone the repo to ~/.rbenv and add it to your PATH
• Install the ruby-build plugin for rbenv install support
• Requires build dependencies like gcc, make, libssl-dev, libyaml-dev
• Run rbenv local 3.x.y in a project root to pin a version
• Use rbenv rehash if shim autodetection is disabled

Key Features

• Minimal footprint — no configuration files or background daemons
• Per-directory automatic version switching via .ruby-version
• Plugin architecture for ruby-build, rbenv-gemset, rbenv-vars, etc.
• Shell completion for bash, zsh, and fish
• Compatible with CI systems and Docker through simple PATH setup

Comparison with Similar Tools

• rvm — feature-rich but modifies shell functions and can conflict with system packages
• asdf — universal version manager supporting many languages; more setup for Ruby-only workflows
• mise — Rust-based polyglot manager with TOML config and task runner built in
• chruby — even more minimal than rbenv but lacks a built-in install command
• Docker — isolates the entire runtime but adds container overhead for local development

FAQ

Q: Does rbenv work on macOS and Linux? A: Yes. Both are fully supported. On macOS you can also install via Homebrew.

Q: How does rbenv differ from rvm? A: rbenv is lighter — it only manages shims and version switching. rvm overrides shell commands and bundles its own dependency installer.

Q: Can I use rbenv in CI pipelines? A: Yes. Clone rbenv and ruby-build, then run rbenv install and rbenv global in your CI script.

Q: How do I remove a Ruby version? A: Run rbenv uninstall 3.x.y or delete the directory ~/.rbenv/versions/3.x.y.

Sources

• https://github.com/rbenv/rbenv
• https://github.com/rbenv/ruby-build