# rbenv — Manage Ruby Versions with Ease

> Pick the right Ruby for every project using lightweight per-directory version switching that never touches your system Ruby.

## Install

Save in your project root:

# rbenv — Manage Ruby Versions with Ease

## Quick Use
```bash
git clone https://github.com/rbenv/rbenv.git ~/.rbenv
echo 'export PATH="$HOME/.rbenv/bin:$PATH"' >> ~/.bashrc
echo 'eval "$(rbenv init -)"' >> ~/.bashrc
source ~/.bashrc
# install ruby-build plugin, then:
rbenv install 3.3.3
rbenv global 3.3.3
```

## 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

---
Source: https://tokrepo.com/en/workflows/41ae5e3b-4211-11f1-9bc6-00163e2b0d79
Author: AI Open Source