> ## Content Index > Fetch the complete content index at: https://rolloutready.com/llms.txt > Use this file to discover other available public pages before exploring further. # How to Install Ruby with rbenv on Mac: A Step-by-Step Guide - URL: https://rolloutready.com/install-ruby-rbenv-mac/ - Published: 2026-10-22T06:00:00.000Z - Updated: 2026-10-22T06:00:00.000Z - Description: This guide teaches you how to install Ruby with rbenv on Mac, manage versions, and configure your environment for smooth development. - Author: Daniel Hayes - Tags: Ruby, MacOS, Development Tools, Programming Managing Ruby versions on a Mac can quickly become confusing, especially when juggling system-installed Ruby and multiple project-specific versions. You might find that your system Ruby is outdated or that switching between versions disrupts your workflow. This article explains how to install Ruby with rbenv on Mac, guiding you through setup, managing multiple Ruby versions, and avoiding common pitfalls. You will learn how to install rbenv, install and switch Ruby versions smoothly, and verify that your environment is correctly configured for development. ## Key takeaways - Install rbenv using Homebrew for straightforward management of Ruby versions. - Set a global Ruby version with `rbenv global` to standardize your environment. - Update your shell configuration to ensure rbenv shims take priority over system Ruby. - Verify Ruby version with `ruby -v` after installation to confirm success. - Address common issues like missing dependencies and PATH misconfiguration early. ## Before you start: What you need to install Ruby with rbenv on Mac Installing Ruby with rbenv on a Mac requires some preparation to avoid common issues. First, ensure your Mac is running macOS with the Command Line Tools installed. These tools include essential compilers and libraries needed for building Ruby versions. You also need Homebrew, the popular package manager for macOS, to install rbenv and its dependencies. Make sure Homebrew is installed and updated to the latest version to prevent conflicts. Basic familiarity with the terminal is necessary since rbenv setup involves running commands and modifying shell configuration files. Finally, a stable internet connection is required to download Ruby source files and packages. 1. Check if Command Line Tools are installed by running **gcc --version**. You should see a version number; if not, install them with *xcode-select --install*. 2. Verify Homebrew is installed by running **brew --version**. Expect to see a version number; if missing, install from *https://brew.sh/*. 3. Update Homebrew by running **brew update**. Success shows updated formulas without errors. 4. Confirm you can use the terminal to run commands like **echo $SHELL** to identify your shell environment (bash, zsh, etc.). ## How to install rbenv on Mac 1. Open your Terminal application on your Mac. 2. Install **rbenv** and the **ruby-build** plugin using Homebrew by running:After installation, you should see messages confirming both packages were installed successfully. - *brew install rbenv ruby-build* 3. Configure your shell to initialize rbenv automatically: - If you use *bash*, add the same line to your *\~/.bash\_profile*. 4. Reload your shell configuration by running *source \~/.zshrc* or *source \~/.bash\_profile*, depending on your shell. 5. Verify that rbenv is set up correctly by running: - *rbenv --version* — this should output a version number like **rbenv 1.2.0**. - *type rbenv* — this should output **rbenv is a function**, confirming the shell integration. If you use *zsh* (default on recent macOS), add the following to your *\~/.zshrc* file: > eval "$(rbenv init -)" Completing these steps ensures rbenv and ruby-build are installed and configured to manage Ruby versions efficiently on your Mac. ## How to install Ruby versions and set a global default with rbenv ![How to install Ruby versions and set a global default with rbenv – how to install Ruby with rbenv on Mac](https://rolloutready.com/content/images/2026/10/install-ruby-rbenv-mac-2.webp) 1. List available Ruby versions by running **rbenv install -l**. You should see a list of Ruby versions, including stable releases like 3.2.2. 2. Install a specific Ruby version, for example, 3.2.2, with **rbenv install 3.2.2**. The terminal will show progress and finish without errors if successful. 3. Set the installed Ruby version as the global default using **rbenv global 3.2.2**. This ensures all terminal sessions use this Ruby version unless overridden. 4. Verify the current Ruby version by running **ruby -v**. Before setting the global version, it might show the system Ruby, for example, *ruby 2.6.3p62*. After setting the global version, it should display *ruby 3.2.2pXXX* (the exact patch number may vary), confirming the switch. ## How to upgrade Ruby version on Mac using rbenv 1. Install the newer Ruby version by running `rbenv install `, replacing `` with the desired Ruby release number (e.g., 3.1.2). Successful installation shows progress messages ending with *Installed Ruby *. 2. Set the new Ruby version as the global default using `rbenv global `. You should see no error and rbenv will now use this version system-wide. 3. Alternatively, set the Ruby version locally for a project folder by navigating to the project directory and running `rbenv local `. This creates a `.ruby-version` file specifying the Ruby version for that directory. 4. Run `rbenv rehash` to refresh rbenv’s shims. The output is typically empty but ensures that your shell recognizes new Ruby executables. 5. Verify the active Ruby version with `ruby -v`. The output should reflect the version you just installed and set, confirming the upgrade. This process lets you smoothly switch between Ruby versions globally or per project without conflict. Remember to always rehash after installing new versions to avoid command errors. ## How to update Ruby version in Mac system environment safely The macOS system Ruby is integral to the operating system, and directly upgrading or modifying it is discouraged because it can cause system instability or break macOS tools that depend on a specific Ruby version. Instead, using **rbenv** to manage Ruby versions allows you to isolate your development environment without affecting the system Ruby. ![How to update Ruby version in Mac system environment safely – how to install Ruby with rbenv on Mac](https://rolloutready.com/content/images/2026/10/install-ruby-rbenv-mac-3.webp) To keep system Ruby untouched and use a newer Ruby version, configure your shell `PATH` so that rbenv’s shims take precedence. This approach lets you switch Ruby versions safely without risking system integrity. | Aspect | System Ruby | rbenv Ruby | | --------------- | --------------------------------- | ------------------------------ | | Upgrade risk | High risk of breaking macOS tools | Safe, isolated environment | | Version control | Fixed by system, hard to change | Flexible per project or global | | System impact | Direct impact, can cause failures | No impact on system Ruby | | Use case | macOS internal scripts and tools | Development and testing | Follow these steps to safely use an updated Ruby version via rbenv without modifying system Ruby: 1. Ensure rbenv is installed and initialized in your shell. You should see `rbenv version` output a version you installed, not the system Ruby. 2. Verify your `PATH` prioritizes rbenv shims by running `echo $PATH`. The path `~/.rbenv/shims` should come before `/usr/bin`. 3. If not set correctly, modify your shell profile (e.g., `~/.zshrc` or `~/.bash_profile`) to add `export PATH="$HOME/.rbenv/shims:$PATH"`, then reload your shell. 4. Install or set your desired Ruby version with rbenv (if not done), then run `rbenv rehash`. 5. Check the active Ruby version with `ruby -v`. It should reflect the rbenv-managed version, confirming system Ruby remains untouched. ## Troubleshooting common rbenv installation issues on Mac If you see **rbenv: command not found** after installation, your shell might not be properly configured. Run *echo $PATH* to check if `~/.rbenv/shims` is included. If missing, add `eval "$(rbenv init -)"` to your shell profile and restart the terminal. Ruby version installation failures often arise from missing dependencies like `openssl` or `readline`. Use Homebrew to install these with *brew install openssl readline* before retrying. When *ruby -v* shows the system Ruby instead of the rbenv version, it usually indicates a PATH priority issue. Ensure that `~/.rbenv/shims` appears before system paths in your environment by running *which ruby*; it should point to the rbenv shim. Permission errors during installation can occur if Homebrew or Ruby directories are owned by root or another user. Fix this by correcting ownership with *sudo chown -R $(whoami) $(brew --prefix)/\** and rerun the installation. 1. Check if rbenv command is recognized by running *rbenv --version*. Successful output means rbenv is installed. 2. Verify PATH includes rbenv shims by running *echo $PATH*. Look for `~/.rbenv/shims`. 3. Diagnose which Ruby runs with *which ruby*. It should point to rbenv's shim path. 4. If Ruby install fails, install dependencies via Homebrew: *brew install openssl readline*. 5. Fix permission issues by adjusting ownership with *sudo chown -R $(whoami) $(brew --prefix)/\**. 6. Restart your terminal or shell session to apply all changes and verify again. ## More on this topic - [How to Install Python 3.13 with Pyenv on Mac: A Step-by-Step Guide](https://rolloutready.com/install-python-3-13-pyenv-mac/) - [How to Install Node.js with NVM on Mac: A Clear Step-by-Step Guide](https://rolloutready.com/install-nodejs-nvm-mac/) - [How to Install Rust on Mac: A Clear Step-by-Step Guide](https://rolloutready.com/install-rust-mac/) - [How to Install Go on Mac: A Step-by-Step Guide for Developers](https://rolloutready.com/install-go-mac/) ## Frequently asked questions ### How to upgrade ruby version mac? To upgrade Ruby on Mac using rbenv, first install the new Ruby version with `rbenv install `. Then set it globally with `rbenv global ` and run `rbenv rehash` to refresh shims. Verify the upgrade by checking `ruby -v` shows the new version. ### How to install rbenv on Mac? Install rbenv on Mac by using Homebrew: run `brew install rbenv` and `brew install ruby-build`. Then add `eval "$(rbenv init -)"` to your shell profile to enable shims and autocompletion. Restart your terminal and confirm installation with `rbenv -v`. ### How to upgrade ruby version Mac? This is a duplicate question of upgrading Ruby on Mac. Use rbenv to install the desired Ruby version and set it as global with `rbenv global `. Afterwards, run `rbenv rehash` and verify with `ruby -v`. ### How to update ruby version in Mac? Updating Ruby version on Mac involves installing a new version via rbenv and configuring your environment to use it. After installing with `rbenv install `, set it globally or locally with `rbenv global ` or `rbenv local `. Run `rbenv rehash` to apply changes, then check with `ruby -v`. ### How to install rbenv on Ubuntu? On Ubuntu, install rbenv by cloning its GitHub repository into `~/.rbenv`, then add `~/.rbenv/bin` to your `PATH` and enable rbenv with `eval "$(rbenv init -)"` in your shell profile. Also, install `ruby-build` as a plugin for Ruby version installation. Restart your terminal and verify with `rbenv -v`. ## What this guide does not cover and when to seek other solutions This guide does not cover installing Ruby on Mac without using Homebrew or managing Ruby versions with alternative tools such as RVM. It assumes you have a basic familiarity with the command line and does not address installation procedures on Windows or Linux systems. If you prefer a graphical interface or need to manage Ruby on non-Mac platforms, other resources may be more appropriate. For many developers and hobbyists, the most useful next step is to verify your rbenv installation by running **rbenv versions** and **ruby -v** in your terminal. This ensures that your system is correctly using the rbenv-managed Ruby rather than the system default. From there, experiment with installing different Ruby versions and setting project-specific versions using **rbenv local** to manage your workflows with precision.