Installing Ruby

Published by Programming Line in Ruby. Last updated .

Installing Ruby means putting a Ruby interpreter — the program that reads your .rb files and runs them — on your machine, along with two tools you will use constantly: RubyGems (Ruby’s package manager) and Bundler (which locks a project’s exact gem versions). The interpreter you’ll install is almost certainly CRuby, also called MRI (Matz’s Ruby Interpreter), the reference implementation written in C by Ruby’s creator, Yukihiro "Matz" Matsumoto. Getting this set up correctly, with a sane way to switch Ruby versions per project, is the first real skill every Ruby developer needs before writing a single line of code.

Overview: How a Ruby Installation Works

Most operating systems already ship with some version of Ruby preinstalled — macOS and many Linux distributions include a "system Ruby" because internal OS tooling sometimes depends on it. You should almost never develop against this system Ruby. It is usually old, installing gems into its directories typically requires sudo (which creates permission headaches and can quietly break OS tools), and you cannot easily run a second, newer version alongside it for a different project.

The standard solution is a Ruby version manager. The most popular are rbenv, RVM, and the multi-language asdf. They all solve the same problem: install several Ruby versions side by side in your own home directory (no sudo needed), and let you pick which version is "active" globally or per project. rbenv does this with a lightweight mechanism called shims — tiny scripts placed early in your PATH that intercept commands like ruby, gem, and bundle, figure out which real version should handle the call (by checking a project-local .ruby-version file, then a global default), and hand off execution to the real binary.

Once a Ruby binary is installed, two companions come bundled with it automatically: RubyGems (bundled since Ruby 1.9) lets you install and require third-party libraries called gems; Bundler (bundled since Ruby 2.6) reads a project’s Gemfile, resolves compatible versions of every gem it needs, and writes them into a Gemfile.lock so that you, your teammates, and your CI server all run the exact same dependency versions. You rarely need to install either separately on a modern Ruby.

Installation Commands at a Glance

The exact commands differ by platform, but the shape is always the same: install a version manager, install a Ruby version through it, then set that version as active. The table below is a quick reference; full worked examples follow.

Platform Recommended tool Core commands
macOS Homebrew + rbenv brew install rbenv ruby-build, then rbenv install 3.3.0
Linux (Debian/Ubuntu) rbenv (built from source) git clone rbenv, then rbenv install 3.3.0
Windows RubyInstaller (with DevKit) or WSL2 winget install RubyInstallerTeam.RubyWithDevKit.3.3

Examples

Example 1: Installing and confirming Ruby on Linux with rbenv

This is the full sequence on a Debian- or Ubuntu-based system: install build dependencies, fetch rbenv and its ruby-build plugin from source, wire rbenv into your shell startup file, install a Ruby version, and make it the default.

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

git clone https://github.com/rbenv/rbenv.git ~/.rbenv
cd ~/.rbenv && src/configure && make -C src
echo 'export PATH="$HOME/.rbenv/bin:$PATH"' >> ~/.bashrc
echo 'eval "$(rbenv init - bash)"' >> ~/.bashrc
source ~/.bashrc

git clone https://github.com/rbenv/ruby-build.git ~/.rbenv/plugins/ruby-build

rbenv install 3.3.0
rbenv global 3.3.0
ruby -v

Output:

ruby 3.3.0p0 (2023-12-25 revision 5124f9ac75) [x86_64-linux]

Each step builds on the last: the apt install line pulls in the C libraries Ruby needs to compile (OpenSSL for networking gems, readline for irb’s line editing, zlib for compression). Cloning rbenv and ruby-build gives you the version manager and its Ruby-compiling plugin. The two echo lines put rbenv’s shims directory at the front of PATH and hook rbenv into every new shell. rbenv install 3.3.0 downloads Ruby’s source and compiles it; rbenv global 3.3.0 writes that version into ~/.rbenv/version as your default. The final ruby -v proves the shim now resolves to the version you just built.

Example 2: Verifying the install with a real Ruby script

Running commands proves the tools exist, but the real test is executing a Ruby file. Save this as check_setup.rb and run it with ruby check_setup.rb.

puts "Hello from Ruby!"
puts "Ruby version: #{RUBY_VERSION}"
puts "Platform: #{RUBY_PLATFORM}"
puts "RubyGems version: #{Gem::VERSION}"

Output (shown for the Ruby 3.3.0 install from Example 1; your version numbers will reflect whatever you installed):

Hello from Ruby!
Ruby version: 3.3.0
Platform: x86_64-linux
RubyGems version: 3.5.7

RUBY_VERSION and RUBY_PLATFORM are built-in global constants every Ruby program has access to without requiring anything; Gem::VERSION comes from RubyGems, which is loaded automatically at interpreter startup. If this script prints sensible values instead of raising a "command not found" error from your shell, your installation is working end to end: the interpreter runs, and it can see RubyGems.

Example 3: Exploring interactively with irb

Every Ruby install also includes irb (Interactive Ruby), a REPL for trying out expressions one line at a time without saving a file. Typing irb at your terminal drops you into a prompt.

$ irb
irb(main):001> 2 + 2
=> 4
irb(main):002> greeting = "Ruby says hi"
=> "Ruby says hi"
irb(main):003> puts greeting
Ruby says hi
=> nil
irb(main):004> exit

Output:

=> 4
=> "Ruby says hi"
Ruby says hi
=> nil

Notice that irb echoes the return value of every expression after =>, which is a great way to internalize that almost everything in Ruby, including a simple addition, produces a value. When you call puts, its printed text ("Ruby says hi") appears first, followed by => nil because puts always returns nil — a detail worth remembering once you start writing methods whose last expression becomes their implicit return value.

How Ruby Installation Works Step by Step

  1. You type ruby -v (or run a .rb file) in your terminal and press Enter.
  2. Your shell searches every directory listed in the PATH environment variable, in order, for an executable named ruby.
  3. If you use rbenv, the very first match is a shim at ~/.rbenv/shims/ruby — a small script, not the real interpreter.
  4. The shim checks, in order, for a project-local .ruby-version file (from rbenv local), then your global default (from rbenv global), to decide which installed version should handle this call.
  5. The shim executes the real binary, for example ~/.rbenv/versions/3.3.0/bin/ruby, passing along all your arguments.
  6. That real Ruby binary starts up, automatically loading RubyGems so require can find installed gems.
  7. If a Gemfile is present and you ran the command through bundle exec, Bundler additionally loads only the exact gem versions locked in Gemfile.lock before your code runs.
  8. Your script’s code executes top to bottom, and any output goes to your terminal via puts, print, or p.

Common Mistakes

Mistake 1: Installing gems with sudo

Wrong:

sudo gem install rails

This installs the gem into directories owned by the system Ruby, not the version-manager Ruby you actually intend to use. It requires root permissions for something that should never need them, can leave files with mixed ownership that cause confusing permission errors later, and often installs the gem against the wrong Ruby entirely, so your project still can’t find it.

Correct:

rbenv global 3.3.0
gem install rails

With a version manager active, your user account owns every installed Ruby and every gem directory, so no sudo is ever necessary.

Mistake 2: Forgetting to load rbenv in your shell startup file

After installing rbenv and a new Ruby version, opening a brand-new terminal and running ruby -v can still print an old system version like ruby 2.6.10. This happens when the line that activates rbenv, eval "$(rbenv init - zsh)" (or the bash equivalent), was run once by hand but never added to ~/.zshrc or ~/.bashrc, so it never runs for new shells.

Fix it by appending the init line to your shell’s startup file and confirming with which ruby — it should point at ~/.rbenv/shims/ruby, not /usr/bin/ruby:

echo 'eval "$(rbenv init - zsh)"' >> ~/.zshrc
source ~/.zshrc
which ruby

Best Practices

  • Never install gems with sudo; use a version manager (rbenv, RVM, or asdf) so your user account owns everything.
  • Pin a project’s Ruby version with a .ruby-version file (rbenv local 3.3.0) so every contributor and your CI server use the same interpreter.
  • Commit Gemfile.lock to version control so gem versions are reproducible on every machine that runs the project.
  • After editing a shell startup file, open a genuinely new terminal window rather than assuming the current one picked up the change.
  • Target Ruby 3.2 or newer for new projects to get pattern matching (case/in), endless method definitions, and recent performance work.
  • After any install or upgrade, verify all three tools: ruby -v, gem -v, and bundle -v.
  • On Windows, pick either RubyInstaller with DevKit or WSL2 for a given project, and don’t mix the two — gems compiled under one won’t work under the other.

Practice Exercises

  • Install Ruby using the version manager appropriate for your operating system, then run ruby -v in a fresh terminal window and confirm the version printed matches what you installed.
  • Write and run a script called check_setup.rb that prints RUBY_VERSION, RUBY_PLATFORM, and Gem::VERSION, similar to Example 2 above.
  • Inside a new project folder, run rbenv local 3.3.0 (or the equivalent for your version manager), confirm a .ruby-version file was created by running cat .ruby-version, and verify that ruby -v run from inside that folder reports the same version.

Summary

  • Installing Ruby means installing the CRuby/MRI interpreter plus its bundled companions, RubyGems and Bundler.
  • Avoid your OS’s built-in system Ruby for development; use a version manager like rbenv, RVM, or asdf instead.
  • rbenv works through lightweight shims on your PATH that pick the right installed version based on a local or global setting, then hand off to the real binary.
  • Verify a fresh install with ruby -v, a real script using RUBY_VERSION/Gem::VERSION, and an interactive irb session.
  • Never use sudo with gem install, and always make sure your version manager’s init line is in your shell’s startup file.
  • Pin versions with .ruby-version and Gemfile.lock so your setup is reproducible across machines and CI.