Ruby on Rails Install How-to

Development System

This appendix shows how to install Ruby and Ruby on Rails on a fresh development machine. It is not meant to cover every Linux distribution or every version of macOS; it shows one well-travelled path that works today.

The recipe in this chapter installs:

  • Ruby 4.0

  • Rails 8.1

  • SQLite (the only database we need for the book)

We use mise as a version manager for Ruby. A version manager lets you install several Rubies side-by-side without touching the Ruby that ships with the operating system. If you prefer rbenv or asdf they both work fine as well, the steps are almost identical.

Older editions of this book used RVM. RVM still works, but on modern machines mise is easier to install, it is faster, and it can also manage Node.js or Python if you ever need them.

macOS (Apple Silicon and Intel)

Tested on macOS 15 (Sequoia) and macOS 26. Earlier versions that still receive security updates should also work.

Xcode Command Line Tools

Ruby ships as source code and needs a C compiler. On macOS that compiler comes with Apple’s Command Line Tools. If you have never installed them, run:

$ xcode-select --install

A system dialog will appear. Click Install and wait for it to finish. You do not need the full Xcode app, only the Command Line Tools.

Homebrew and mise

Homebrew is the de-facto package manager on macOS. If you do not have it yet, install it with the one-liner from the Homebrew homepage.

Once Homebrew is installed, add mise:

$ brew install mise

Then activate mise in your shell. For Zsh (the default on macOS) add this line to ~/.zshrc:

eval "$(mise activate zsh)"

Open a new terminal window so the change takes effect.

Install Ruby

$ mise use --global ruby@4.0

The first run compiles Ruby, which takes a few minutes. When it is done, check the version:

$ ruby -v
ruby 4.0.2 (2026-03-17 revision d3da9fec82) +PRISM [arm64-darwin25]

Install Rails

Rails is just a Ruby gem. Install the latest stable release:

$ gem install rails

Verify:

$ rails -v
Rails 8.1.3
gem install rails always fetches the current stable Rails. To pin a specific version use gem install rails -v 8.1.3. For a pre-release add --pre.

That’s it. You are ready to create your first Rails application.

Linux (Debian/Ubuntu)

Tested on Debian 13 (Trixie) and Ubuntu 24.04 LTS. Other modern distributions use the same idea, only the package names change.

Build dependencies

Ruby still compiles from source, so you need a C compiler and a handful of libraries. Log in as a normal user and run:

$ sudo apt update
$ sudo apt install -y build-essential curl git libssl-dev \
    libreadline-dev zlib1g-dev libyaml-dev libffi-dev \
    libgmp-dev libsqlite3-dev sqlite3 pkg-config

mise

The mise homepage has an installer. The short version:

$ curl https://mise.run | sh
$ echo 'eval "$(~/.local/bin/mise activate bash)"' >> ~/.bashrc

Open a new terminal.

Ruby and Rails

The rest is identical to the macOS path:

$ mise use --global ruby@4.0
$ ruby -v
ruby 4.0.2 (2026-03-17 revision d3da9fec82) [aarch64-linux]
$ gem install rails
$ rails -v
Rails 8.1.3

Windows (WSL 2)

The recommended way to develop Rails applications on Windows is not native Windows at all, but the Windows Subsystem for Linux. You get a real Linux environment, your editor on Windows talks to it over the filesystem bridge, and every Linux gem (including ones with C extensions) just works.

Open an elevated PowerShell and run:

PS> wsl --install

Reboot when prompted. After the reboot Windows installs Ubuntu and asks you to pick a Linux username and password. From that point on, follow the Linux instructions above inside the Ubuntu window.

What you just installed

After running the commands above you have:

  • A Ruby 4.0 interpreter, managed by mise, living under your home directory so it cannot collide with the system Ruby.

  • RubyGems 4.0, which is the package manager for Ruby libraries ("gems"). gem install X downloads and installs the gem X.

  • Bundler, which is bundled with Ruby 4.0 and is the tool every Rails application uses to lock its dependencies to known versions (see Bundler and Gems).

  • The Rails gem itself. rails new myapp creates a new Rails application.

Whenever you want to try a fresh Ruby version later, mise install ruby@X.Y installs it and mise use ruby@X.Y switches. Your existing projects are unaffected because each Rails project pins its Ruby version in a .ruby-version file in the project root.