Repository files navigation

ruby-build is a command-line tool that simplifies installation of any Ruby version from source on Unix-like systems.

It is available as a plugin forrbenv as therbenv install command, or as a standalone program as theruby-build command.

brew install ruby-build

Upgrade with:

brew upgrade ruby-build

git clone https://github.com/rbenv/ruby-build.git"$(rbenv root)"/plugins/ruby-build

Upgrade with:

git -C"$(rbenv root)"/plugins/ruby-build pull

First, download a tarball fromhttps://github.com/rbenv/ruby-build/releases/latest. Then:

tar -xzf ruby-build-*.tar.gzPREFIX=/usr/local ./ruby-build-*/install.sh

# As a standalone program$ ruby-build --list# lists latest stable releases for each Ruby$ ruby-build --definitions# lists all definitions, including outdated ones$ ruby-build 3.2.2~/.rubies/ruby-3.2.2# installs Ruby 3.2.2$ ruby-build -d ruby-3.2.2~/.rubies# alternate form for the previous example# As an rbenv plugin$ rbenv install 3.2.2# installs Ruby 3.2.2 to ~/.rbenv/versions/3.2.2

Basically, what ruby-build does when installing a Ruby version is this:

• Downloads an official tarball of Ruby source code;
• Extracts the archive into a temporary directory on your system;
• Executes./configure --prefix=/path/to/destination in the source code;
• Runsmake install to compile Ruby;
• Verifies that the installed Ruby is functional.

Depending on the context, ruby-build does a little bit more than the above: for example, it will try to link Ruby to the appropriate OpenSSL version, even if that means downloading and compiling OpenSSL itself; it will discover and link to Homebrew-installed instances of some libraries like libyaml and readline, etc.

To install a version of Ruby that is not available in ruby-build, you can specify the path to a custom build definition file in place of a Ruby version number.

# As a standalone program$ ruby-build -d /path/to/3.4-custom /opt/rubies# installs to /opt/rubies/3.4-custom# As an rbenv plugin$ rbenv install /path/to/3.4-custom# installs to $(rbenv root)/versions/3.4-custom

You can also provide adirectory of custom build definition files.The path(s) will be searched along with ruby-build's bundledshare/ruby-build/ directory.(Perhaps a collection of 3rd-party build definitions published as a git repo,or an organization's custom build definitions distributed in-house.)

# As a standalone program$ RUBY_BUILD_DEFINITIONS=/path/to/custom/defs ruby-build --definitions# lists all available versions of Ruby, including custom defs$ RUBY_BUILD_DEFINITIONS=/path/to/custom/defs ruby-build -d 3.5-custom /opt/rubies# installs to /opt/rubies/3.5-custom# As an rbenv plugin$ RUBY_BUILD_DEFINITIONS=/path/to/custom/defs rbenv install --list# lists all available versions of Ruby, including custom defs$ RUBY_BUILD_DEFINITIONS=/path/to/custom/defs rbenv install 3.5-custom# installs to $(rbenv root)/versions/3.5-custom

Check outdefault build definitions as examples on how to write definition files.

The build process may be configured through the following environment variables:

Bothrbenv install andruby-build commands support the-p/--patch flag to apply a patch to the Ruby source code before building. Patches are read from standard input:

# applying a single patch$ rbenv install --patch 1.9.3-p429< /path/to/ruby.patch# applying a patch from HTTP$ rbenv install --patch 1.9.3-p429<<(curl -sSL http://git.io/ruby.patch)# applying multiple patches$ cat fix1.patch fix2.patch| rbenv install --patch 1.9.3-p429

All Ruby definition files bundled with ruby-build include checksums for packages, meaning that all externally downloaded packages are automatically checked for integrity after fetching.

See the next section for more information on how to author checksums.

You may specify a custom mirror by settingRUBY_BUILD_MIRROR_URL. When set,ruby-build will first attempt to download packages from the mirror before fallingback to the original URL.

# example:export RUBY_BUILD_MIRROR_URL="https://my-mirror.example.com"install_package"ruby-2.6.5""https://ruby-lang.org/ruby-2.6.5.tgz#<SHA2>"# Will first try: https://my-mirror.example.com/<SHA2>

ruby-build will first try to fetch this package from$RUBY_BUILD_MIRROR_URL/<SHA2>(note: this is the complete URL), where<SHA2> is the checksum for the file. Itwill fall back to downloading the package from the original location if:

• the package was not found on the mirror;
• the mirror is down;
• the download is corrupt, i.e. the file's checksum doesn't match;
• no tool is available to calculate the checksum; or
• RUBY_BUILD_SKIP_MIRROR is enabled.

If a mirror site doesn't conform to the above URL format, you can specify thecomplete URL by settingRUBY_BUILD_MIRROR_PACKAGE_URL. It behaves the same asRUBY_BUILD_MIRROR_URL except being a complete URL.

Bothruby-build andrbenv install accept the-k or--keep flag, whichtells ruby-build to keep the downloaded source after installation. This can beuseful if you need to usegdb andmemprof with Ruby.

Source code will be kept in a parallel directory tree~/.rbenv/sources whenusing--keep with therbenv install command. You should specify thelocation of the source code with theRUBY_BUILD_BUILD_PATH environmentvariable when using--keep withruby-build.

Please see theruby-build wiki for solutions to common problems.

If you can't find an answer on the wiki, open an issue on theissue tracker.Be sure to include the full build log for build failures.