Ruby Source Build and Installation Guide

This guide covers building the Ruby programming language from source code. For pre-built binaries, see ruby-lang.org/downloads.

Prerequisites

Building Ruby from source requires a POSIX-compatible environment with the following tools:

Required Build Tools:

C compiler (GCC 4.9+ or Clang 3.5+)
GNU Make or BSD Make
Autoconf 2.71+
Bison 2.0+
Git

Required Libraries:

OpenSSL development headers (libssl-dev or openssl-devel)
zlib development headers (zlib1g-dev or zlib-devel)
Readline development headers (libreadline-dev or readline-devel)

Platform-Specific Packages:

Ubuntu/Debian:

sudo apt-get install -y git autoconf bison build-essential \
    libssl-dev libyaml-dev libreadline-dev zlib1g-dev \
    libncurses-dev libffi-dev libgdbm-dev

RHEL/CentOS/Fedora:

sudo yum install -y git autoconf bison gcc make \
    openssl-devel libyaml-devel readline-devel zlib-devel \
    ncurses-devel libffi-devel gdbm-devel

macOS (with Homebrew):

brew install autoconf openssl readline libyaml gdbm

Installation

Clone the Ruby source repository:

git clone https://github.com/ruby/ruby.git
cd ruby

For committers, use the canonical repository:

git clone https://git.ruby-lang.org/ruby.git

Configuration

Generate the configure script and set installation options:

# Generate configure script (only needed for Git clones, not release tarballs)
autoconf

Configure the build with installation prefix:

# Install to user directory (recommended for development)
./configure --prefix="$HOME/.rubies/ruby-master"

# Or install system-wide (requires root for make install)
./configure --prefix=/usr/local

# With specific OpenSSL path (macOS Homebrew example)
./configure --prefix="$HOME/.rubies/ruby-master" \
    --with-openssl-dir=$(brew --prefix openssl)

Common Configure Options:

--prefix=PATH: Installation directory
--enable-shared: Build shared libraries (libruby.so)
--disable-install-doc: Skip building documentation (faster)
--with-opt-dir=PATH: Additional library search path
--enable-debug-env: Enable debug build

Build & Run

Compile Ruby:

make -j$(nproc)

Run the test suite (optional but recommended):

make test
# or for more comprehensive testing
make test-all

Test the built binary without installing:

./ruby -v
./ruby -e "puts 'Hello, Ruby!'"

Install to the configured prefix:

make install

Add to PATH:

export PATH="$HOME/.rubies/ruby-master/bin:$PATH"
ruby -v

Deployment

Since Ruby is a language runtime, "deployment" refers to installing the built interpreter for use by applications.

Local User Installation:

./configure --prefix="$HOME/.local"
make install
# Add $HOME/.local/bin to PATH

System-Wide Installation:

./configure --prefix=/usr/local
sudo make install

Container Deployment:

FROM ubuntu:22.04
RUN apt-get update && apt-get install -y build-essential autoconf bison \
    libssl-dev libyaml-dev zlib1g-dev
COPY . /ruby
WORKDIR /ruby
RUN autoconf && ./configure --prefix=/usr/local && make -j$(nproc) && make install

Using with Ruby Managers: After make install, the built Ruby can be registered with rbenv or chruby:

# For rbenv
ln -s "$HOME/.rubies/ruby-master" ~/.rbenv/versions/ruby-master
rbenv global ruby-master

Troubleshooting

"autoconf: command not found"

Install autoconf via your package manager

"bison: command not found"

Install bison (required for parsing Ruby's grammar)

"C compiler cannot create executables"

Install build-essential (Ubuntu) or Xcode Command Line Tools (macOS)

Missing header files during configure:

Install -dev or -devel packages for the missing library (e.g., libssl-dev for openssl/ssl.h)

Test failures in make test-all:

Some tests may fail due to locale or timezone settings. Set:
```
export LANG=C
export TZ=UTC
```

Permission denied during make install:

Ensure the --prefix directory is writable, or use sudo only for the install step

Linking errors on macOS:

Ensure Xcode Command Line Tools are installed: xcode-select --install
May need to specify SDK path: ./configure --with-opt-dir=$(xcrun --show-sdk-path)/usr

For detailed build documentation, see Building Ruby.