Installation #

Ruby is available on every major operating system, but the most appropriate installation method depends on your system and how you plan to use it. There is a fundamental difference between installing Ruby for a single small project versus managing many projects that each require a different Ruby version. Understanding this difference before you start installing will save you a lot of time and frustration down the road. This article covers all the common installation methods — from the simplest to the most flexible — and when you should choose one over the other.

Choosing the Right Installation Method #

Before diving into the technical steps, it’s important to understand the difference between the two approaches to installing Ruby: installing directly to your system and installing with a version manager.

DIRECT INSTALLATION (RubyInstaller / Homebrew / APT / YUM):
  ✓ Simpler, great for learning and initial exploration
  ✓ No need to understand version management concepts
  ✓ Enough for a single project or a single Ruby version
  ✗ Hard to run two projects that need different Ruby versions
  ✗ Upgrading Ruby can be problematic if you're not careful
  ✗ Not recommended for production environments

INSTALLATION VIA VERSION MANAGER (RVM / rbenv):
  ✓ Install and switch between many Ruby versions
  ✓ Each project can be pinned to a specific version
  ✓ Industry standard for professional Ruby developers
  ✓ Makes collaboration easier since versions can be locked per project
  ✗ Slightly more complex initial setup
  ✗ Requires a basic understanding of PATH and shell configuration

If you’re new to Ruby and aren’t sure you want to commit to it seriously, a direct installation is enough. But if you plan to work on real projects — especially Ruby on Rails — use a version manager from the start. Migrating from a direct installation to RVM or rbenv later is more hassle than you’d think.

Installing Ruby on Windows #

Windows isn’t the primary platform for Ruby development, but the ecosystem is mature enough thanks to RubyInstaller. There are two paths: using RubyInstaller, which runs directly on Windows, or using WSL (Windows Subsystem for Linux), which gives you a full Linux environment inside Windows.

Using RubyInstaller #

RubyInstaller is the fastest way to get started with Ruby on Windows. The installer already bundles all required dependencies, including the C compiler needed to install some native gems.

Step 1 — Download RubyInstaller

Visit rubyinstaller.org and choose the version that fits. You’ll see two variants: Ruby and Ruby+Devkit. For application development that will use gems with native extensions (like Nokogiri or pg), choose Ruby+Devkit because it already includes MSYS2 and the required compiler.

Choosing a version on RubyInstaller:

  Ruby (x64)          → Ruby interpreter only
  Ruby+Devkit (x64)   → Ruby + MSYS2 + build tools (RECOMMENDED)

Pick the version labeled "(RECOMMENDED)" if one is available — it's
usually the latest minor release of the stable line.

Step 2 — Run the Installer

Once the .exe file is downloaded, double-click it to run it. Follow the installation wizard, keeping one important thing in mind:

□ Check the option: "Add Ruby executables to your PATH"
□ Check the option: "Associate .rb and .rbw files with this Ruby installation"

Don’t skip the PATH checkbox — without it, you’ll have to type the full path every time you run a Ruby command in the terminal.

Step 3 — Install MSYS2 and the Toolchain (Ruby+Devkit only)

After the installer finishes, a Command Prompt window opens automatically asking whether you want to install MSYS2. Press Enter or type 1 to install the standard toolchain — this is required to compile native gems.

# If the window doesn't appear automatically, run:
ridk install

Choose option 1 (MSYS2 base installation) or 3 (MSYS2 and MINGW development toolchain) for a complete installation.

Step 4 — Verify the Installation

Open a new Command Prompt (important: not the old one, since PATH changes only take effect in a new session) and run:

ruby -v
gem -v
irb --version

Expected output:

ruby 3.3.x (2024-xx-xx revision xxxxxxxx) [x64-mingw-ucrt]
3.x.x
irb x.x.x (2024-xx-xx)

Using Windows Subsystem for Linux (WSL) #

WSL is a better choice if you plan to seriously develop Ruby applications, especially Ruby on Rails. The Linux environment you get from WSL is far more compatible with modern Ruby tooling than native Windows.

When to choose WSL over RubyInstaller:
  ✓ Planning to work on Ruby on Rails projects
  ✓ Want to use rbenv or RVM
  ✓ Your team uses Linux or macOS
  ✓ You'll deploy to Linux servers
  ✗ Just want to learn basic Ruby quickly

Step 1 — Enable WSL

Open PowerShell as Administrator (right-click > “Run as Administrator”) and run:

wsl --install

This command enables WSL and installs Ubuntu automatically. Restart your computer when the process finishes.

Step 2 — Set Up Ubuntu

After the restart, Ubuntu will open and ask you to create a username and password. Use a username and password you’ll remember easily — these are separate from your Windows account.

Step 3 — Install Ruby in WSL

Once you’re inside the Ubuntu WSL terminal, follow the Linux installation steps in the next section. All the Linux commands apply here.

Don’t store your Ruby project files inside the Windows filesystem (/mnt/c/Users/...) when using WSL. I/O performance between WSL and the Windows filesystem is very slow and will make commands like bundle install or rails server feel sluggish. Keep your projects in the WSL home directory (~/projects/) for optimal performance.

Installing Ruby on macOS #

macOS ships with a built-in Ruby, but don’t use this system Ruby for development. The system Ruby is used by macOS itself for some internal scripts, and modifying it or installing gems into it can cause unexpected problems with your operating system.

DON'T use macOS's built-in Ruby for development:
  ✗ /usr/bin/ruby       → System Ruby, owned by macOS
  ✗ /usr/local/bin/ruby → Can overwrite a system installation

USE one of these instead:
  ✓ Homebrew → /opt/homebrew/bin/ruby  (for Apple Silicon)
  ✓ RVM      → ~/.rvm/rubies/ruby-x.x.x/bin/ruby
  ✓ rbenv    → ~/.rbenv/versions/x.x.x/bin/ruby

Using Homebrew #

Homebrew is the most commonly used package manager on macOS. Installing Ruby via Homebrew is quick and easy, making it a good starting point.

Step 1 — Install Homebrew

If Homebrew isn’t installed yet, open Terminal and run:

/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

This process will ask for your administrator password and install Xcode Command Line Tools if they’re missing. Follow all the on-screen instructions.

When it’s done, if you’re using a Mac with an Apple Silicon chip (M1/M2/M3), add Homebrew to your PATH by running the command shown at the end of the installation. It usually looks like this:

echo 'eval "$(/opt/homebrew/bin/brew shellenv)"' >> ~/.zprofile
eval "$(/opt/homebrew/bin/brew shellenv)"

Step 2 — Install Ruby

brew install ruby

After the installation finishes, Homebrew will show a message saying Ruby isn’t linked automatically because it conflicts with the macOS built-in Ruby. Add the Homebrew Ruby to your PATH manually:

# For Apple Silicon (M1/M2/M3):
echo 'export PATH="/opt/homebrew/opt/ruby/bin:$PATH"' >> ~/.zshrc

# For Intel Macs:
echo 'export PATH="/usr/local/opt/ruby/bin:$PATH"' >> ~/.zshrc

# Apply the changes:
source ~/.zshrc

Step 3 — Verify the Installation

which ruby    # Should show the Homebrew path, not /usr/bin/ruby
ruby -v
gem -v

Using RVM on macOS #

RVM (Ruby Version Manager) lets you install and switch between many Ruby versions. It’s a better choice if you plan to work on several Ruby projects with different version requirements.

Step 1 — Install the GPG Key

RVM verifies its packages using GPG. Install the RVM public key first:

gpg --keyserver keyserver.ubuntu.com --recv-keys 409B6B1796C275462A1703113804BB82D39DC0E3 7D2BAF1CF37B13E2069D6956105BD0E739499BDB

Step 2 — Install RVM

\curl -sSL https://get.rvm.io | bash -s stable

Note the backslash (\) before curl — it prevents the use of a curl alias if one exists. After installation, load RVM into your terminal session:

source ~/.rvm/scripts/rvm

Or close the terminal and open a new one.

Step 3 — Install Ruby via RVM

See which Ruby versions are available:

rvm list known

Install the Ruby version you want:

# Install the latest version:
rvm install ruby

# Or install a specific version:
rvm install 3.3.0

# Set it as default:
rvm use 3.3.0 --default

Step 4 — Verify

ruby -v
rvm list        # See all installed Ruby versions
rvm current     # The currently active version

Installing Ruby on Linux #

Linux is the primary platform for Ruby development, especially for server applications. Every Linux distribution has a different package manager, but the most flexible choice remains RVM or rbenv.

Using APT (Debian/Ubuntu) #

APT is the fastest way to install Ruby on Debian, Ubuntu, Linux Mint, and other Debian-based distributions.

Step 1 — Update the Repository

Always update the package list before installing:

sudo apt update && sudo apt upgrade -y

Step 2 — Install Dependencies

Ruby needs a few libraries to compile and run correctly:

sudo apt install -y build-essential libssl-dev libreadline-dev \
  zlib1g-dev libsqlite3-dev curl git

Step 3 — Install Ruby

sudo apt install -y ruby-full

The ruby-full flag installs the Ruby interpreter along with the complete standard library, not just a minimal version.

Step 4 — Configure Gems for the Local User

By default, gem install on Linux requires sudo to write to system directories. Configure Gem to install into your home directory:

echo '# Gem path configuration' >> ~/.bashrc
echo 'export GEM_HOME="$HOME/.gem"' >> ~/.bashrc
echo 'export PATH="$HOME/.gem/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc

Step 5 — Verify

ruby -v
gem -v
gem environment  # See the full Gem configuration

Using YUM/DNF (CentOS/RHEL/Fedora) #

For Red Hat-based distributions like Fedora, CentOS, Rocky Linux, and AlmaLinux.

Install Build Dependencies:

# Fedora / CentOS 8+ / RHEL 8+ / Rocky Linux / AlmaLinux:
sudo dnf install -y gcc make openssl-devel readline-devel \
  zlib-devel libffi-devel git curl

# CentOS 7 / RHEL 7:
sudo yum install -y gcc make openssl-devel readline-devel \
  zlib-devel libffi-devel git curl

Install Ruby:

# Fedora / CentOS 8+ / RHEL 8+:
sudo dnf install -y ruby ruby-devel rubygems

# CentOS 7 / RHEL 7:
sudo yum install -y ruby ruby-devel rubygems

The Ruby version available in the YUM/DNF repositories is often several releases behind the latest. For example, CentOS 7 ships Ruby 2.0, which is quite outdated. For newer Ruby versions on RHEL-based systems, use RVM or rbenv, or enable Software Collections (SCL) if available on your distribution.

Verify:

ruby -v
gem -v

Using RVM on Linux #

RVM on Linux works the same way as on macOS. It’s the recommended choice for developers working with multiple Ruby projects.

Step 1 — Install Dependencies

# Ubuntu/Debian:
sudo apt install -y curl gnupg2

# Fedora/CentOS/RHEL:
sudo dnf install -y curl gnupg2

Step 2 — Import the GPG Key

gpg --keyserver keyserver.ubuntu.com --recv-keys 409B6B1796C275462A1703113804BB82D39DC0E3 7D2BAF1CF37B13E2069D6956105BD0E739499BDB

Step 3 — Install RVM

\curl -sSL https://get.rvm.io | bash -s stable

When it’s done, load RVM into your session:

source ~/.rvm/scripts/rvm

Or add it to .bashrc / .zshrc so it loads automatically every time you open a terminal:

echo 'source ~/.rvm/scripts/rvm' >> ~/.bashrc
source ~/.bashrc

Step 4 — Install Ruby

# Install the latest version:
rvm install ruby

# Or a specific version:
rvm install 3.3.0

# Make it the default:
rvm use 3.3.0 --default

# Verify:
ruby -v
rvm list

Using rbenv #

rbenv is a lighter alternative to RVM. Unlike RVM, which uses shell functions to switch versions, rbenv works by manipulating the PATH. Developers who prefer a transparent, minimal approach often pick rbenv.

RVM vs rbenv comparison:

Feature                 RVM         rbenv
─────────────────────────────────────────
Installation size       Large       Small
How it works            Shell fn    PATH shims
Separate gemsets        ✓           ✗ (use bundler)
.ruby-version support   ✓           ✓
Complexity              Medium      Low
Community               Large       Large

Step 1 — Install rbenv

curl -fsSL https://github.com/rbenv/rbenv-installer/raw/main/bin/rbenv-installer | bash

This script installs rbenv along with the ruby-build plugin needed to download and compile Ruby versions.

Step 2 — Configure the Shell

Add rbenv to your PATH and initialize it:

# For Bash:
echo 'export PATH="$HOME/.rbenv/bin:$PATH"' >> ~/.bashrc
echo 'eval "$(rbenv init - bash)"' >> ~/.bashrc
source ~/.bashrc

# For Zsh:
echo 'export PATH="$HOME/.rbenv/bin:$PATH"' >> ~/.zshrc
echo 'eval "$(rbenv init - zsh)"' >> ~/.zshrc
source ~/.zshrc

Verify rbenv is configured correctly:

rbenv doctor

Expected output:

Checking for `rbenv' in PATH: /home/user/.rbenv/bin/rbenv
Checking for rbenv shims in PATH: OK
Checking `rbenv install' support: /home/user/.rbenv/plugins/ruby-build/bin/rbenv-install (ruby-build x.x.x)
Counting installed Ruby versions: none
  There aren't any Ruby versions installed under `/home/user/.rbenv/versions'.
  You can install Ruby versions like so: rbenv install 3.3.0
Auditing installed plugins: OK

Step 3 — Install Ruby

See all available Ruby versions:

rbenv install --list          # Latest stable versions
rbenv install --list-all      # All versions including previews

Install the version you want:

rbenv install 3.3.0

This process downloads the Ruby source code and compiles it from scratch — it can take a few minutes depending on your machine’s specs.

Step 4 — Set the Ruby Version

# Set globally (default for all projects):
rbenv global 3.3.0

# Set locally (only for the current directory and its subdirectories):
cd ~/projects/my-app
rbenv local 3.2.0   # Creates a .ruby-version file in this directory

Step 5 — Verify

ruby -v
rbenv versions       # All installed versions
rbenv version        # The currently active version
which ruby           # Should point to the rbenv shim

Comprehensive Installation Verification #

After installing Ruby with any method, run a thorough verification to make sure everything works correctly.

# 1. Check the Ruby version
ruby -v

# 2. Check the Gem version (Ruby's package manager)
gem -v

# 3. Check the Bundler version (dependency manager for projects)
bundler -v    # Or: bundle -v

# 4. Run a simple Ruby one-liner from the command line:
ruby -e 'puts "Ruby is running smoothly!"'

# 5. Open IRB (Interactive Ruby), type some code, press Enter:
irb

Inside IRB, try a few commands:

# Basic tests
puts "Hello from Ruby!"
2 + 2
"Ruby".upcase
[1, 2, 3].map { |n| n * 2 }

Verification flowchart:

flowchart TD
    A[Install Complete] --> B{ruby -v works?}
    B -- No --> C[Check PATH configuration]
    C --> D[Add Ruby to PATH]
    D --> E[Restart terminal]
    E --> B
    B -- Yes --> F{gem -v works?}
    F -- No --> G[Reinstall Ruby with the ruby-full flag]
    G --> F
    F -- Yes --> H{IRB opens?}
    H -- Yes --> I[✓ Installation successful]
    H -- No --> J[Check readline library]
    J --> K[sudo apt install libreadline-dev]
    K --> H

Installing Bundler #

Once Ruby is installed, install Bundler. Bundler is the dependency manager for Ruby projects and is needed in almost every case, especially for Ruby on Rails.

gem install bundler

Verify:

bundler -v

Bundler reads the Gemfile in your project directory to install all the dependencies that project needs. It’s a tool you’ll use every time you start a new Ruby project.

Managing Ruby Versions per Project #

If you use RVM or rbenv, you can lock the Ruby version used by each project using a .ruby-version file.

# In the project directory:
echo "3.3.0" > .ruby-version

# rbenv detects this file automatically
# RVM supports the same format too

This matters for team collaboration — every developer will automatically use the same Ruby version.

sequenceDiagram
    participant Dev as Developer
    participant Shell as Shell
    participant rbenv as rbenv/RVM
    participant Ruby as Ruby Binary

    Dev->>Shell: cd my-project/
    Shell->>rbenv: Read .ruby-version
    rbenv->>Shell: Activate Ruby 3.3.0
    Dev->>Shell: ruby script.rb
    Shell->>Ruby: Run with Ruby 3.3.0
    Ruby-->>Dev: Program output

Updating Ruby #

How you update Ruby depends on the installation method you used.

Using RVM:

# Update the list of available versions:
rvm get stable

# Install the new version:
rvm install 3.4.0

# Migrate gems from the old version:
rvm upgrade 3.3.0 3.4.0

# Set it as default:
rvm use 3.4.0 --default

Using rbenv:

# Update ruby-build to get the latest versions:
cd ~/.rbenv/plugins/ruby-build && git pull

# Install the new version:
rbenv install 3.4.0

# Set globally:
rbenv global 3.4.0

# Or update per project:
rbenv local 3.4.0

Using Homebrew:

brew upgrade ruby

Using APT:

sudo apt update && sudo apt upgrade ruby

After upgrading the Ruby version with rbenv or RVM, the gems you installed on the old version aren’t automatically available on the new one. You’ll need to run bundle install again in every project to reinstall all dependencies on the new Ruby version. This is intended behavior because it ensures each Ruby version has a clean, isolated set of gems.

Summary #

Pick the method based on your needs — RubyInstaller for Windows beginners, Homebrew for a quick macOS setup, APT/YUM for single-project Linux use, and RVM/rbenv for professional development that needs multiple versions.
Don’t use the system Ruby on macOS — /usr/bin/ruby belongs to the operating system, not to development. Always install a separate Ruby.
RVM and rbenv are the industry standard — if you plan to work on serious Ruby projects, set up a version manager from day one.
The .ruby-version file for team collaboration — create this file at the project root so the whole team uses the same Ruby version automatically.
Install Bundler right after Ruby — almost every Ruby project uses it, including Ruby on Rails.
Configure GEM_HOME on Linux — so gem install doesn’t require sudo and gems are installed in your home directory.
Verify with ruby -v, gem -v, and IRB — these three commands are enough to confirm the installation works correctly.
Update ruby-build regularly — if you use rbenv, the ruby-build plugin needs periodic updates so it can install the latest Ruby versions.

← Previous: Introduction Next: Core Syntax →