ruby-build: compiling Ruby from source without touching your system Ruby

What ruby-build solves, and who ends up using it

A distribution package manager gives you the Ruby version that distribution decided to ship. If a project pins Ruby 3.4.9, or if you maintain several applications on different Ruby versions on one machine, that is not enough. ruby-build exists to install a named Ruby version from its official source tarball into a destination directory you choose, so the installed interpreter does not overwrite or depend on the system Ruby.

The README describes it as both a plugin for rbenv (where it becomes the rbenv install command) and a standalone program called ruby-build. That dual identity explains most of its design. As a plugin it installs into $(rbenv root)/versions/; as a standalone program you pass the destination explicitly, for example ruby-build 3.4.9 ~/.rubies/ruby-3.4.9. The README also notes that ruby-build ships definitions for CRuby, jruby, mruby, picoruby, truffleruby and truffleruby+graalvm, so it is not only a CRuby installer even though that is the common case.

The install pipeline: tarball, configure, make install, verify

The README spells out the sequence plainly. ruby-build downloads an official tarball of Ruby source code, extracts the archive into a temporary directory, runs ./configure --prefix=/path/to/destination inside the source tree, runs make install to compile Ruby, and finally verifies that the installed Ruby is functional. That last step matters: a build that produces a binary which fails to start is treated as a failure rather than a success.

The README adds that the tool does more than that in some contexts. It will try to link Ruby to the appropriate OpenSSL version, which can mean downloading and compiling OpenSSL itself. It will also discover and link Homebrew-installed instances of libraries such as libyaml and readline. Those two behaviours are where most surprises come from: the build can pull in extra compilation work, and it can silently prefer a Homebrew library over a system one.

Definitions are bundled, not fetched. Each Ruby version has a definition file under share/ruby-build/, which is why ruby-build only knows about versions that shipped with the copy you have installed. The repository layout confirms this: share/ sits next to bin/, install.sh, script/ and test/.

Installing ruby-build and compiling a first Ruby

Homebrew users get the short path. The README gives this command, and upgrading is a separate brew upgrade ruby-build call.

brew install ruby-build

If you already run rbenv, cloning the repository into rbenv's plugin directory is the alternative. The command uses $(rbenv root) to find that directory, so rbenv must be on PATH first.

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

Upgrade that clone with a git pull in the same directory.

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

For a standalone install without Homebrew, download a tarball from the releases page, extract it, and run the bundled installer with a PREFIX. The README shows exactly this shape.

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

Now the first real use. Ask what is available before installing anything.

ruby-build --list

The README says this lists the latest stable release for each Ruby implementation. Then install one into a directory you own.

ruby-build 3.4.9 ~/.rubies/ruby-3.4.9

The README notes that the -d form is equivalent: ruby-build -d ruby-3.4.9 ~/.rubies produces the same result, and ruby-build -d ruby-3.4 ~/.rubies installs the latest Ruby 3.4.x. Expect a long compile. If your machine lacks a compiler or development headers, this is the point where it fails, and the README's own warning says ruby-build mostly does not check for those dependencies before it starts downloading and compiling.

The dependency check that ruby-build deliberately does not do

The README carries a warning block stating that ruby-build mostly does not verify that system dependencies are present before downloading and attempting to compile Ruby from source. It directs the reader to ensure that all requisite libraries, such as build tools and development headers, are already installed. This is the single most important limitation to internalise, because the failure arrives late: after the download, after extraction, after configure has begun. On a fresh container image the usual outcome is a configure or make error that names a missing header, not a clear message from ruby-build itself.

The second limitation is version lag. Because definitions are bundled, a Ruby release that came out after your copy of ruby-build will not appear in ruby-build --list and cannot be installed by version number until you upgrade the tool. The README states this directly and points readers who need an installer that always consults remote resources toward ruby-install instead. If your workflow depends on installing a Ruby on the day it is released, ruby-build is the wrong shape of tool unless you also automate the upgrade.

A third boundary is scope. ruby-build compiles and installs; it does not switch between installed Rubies for you. That job belongs to rbenv or to whatever else manages your PATH. Using ruby-build standalone means you own that part yourself.

Custom definitions and the environment variables that change a build

When a version you need is not bundled, you can point ruby-build at a definition file path instead of a version number. The README gives ruby-build -d /path/to/3.4-custom /opt/rubies as the standalone form, which installs to /opt/rubies/3.4-custom, and rbenv install /path/to/3.4-custom as the plugin form, which installs to $(rbenv root)/versions/3.4-custom. A directory of definitions works too: set RUBY_BUILD_DEFINITIONS to that path and it is searched alongside the bundled share/ruby-build/ directory. The README suggests this for a third-party collection published as a git repository or an organisation's in-house definitions.

Build behaviour is configured through environment variables. TMPDIR controls where temporary files go. RUBY_BUILD_BUILD_PATH controls where sources are downloaded and built, defaulting to a timestamped subdirectory of TMPDIR. RUBY_BUILD_CACHE_PATH controls where downloaded package files are cached, defaulting to ~/.rbenv/cache when invoked as an rbenv plugin. RUBY_BUILD_HTTP_CLIENT selects one of aria2c, curl or wget, defaulting to the first one found on PATH, and RUBY_BUILD_ARIA2_OPTS, RUBY_BUILD_CURL_OPTS and RUBY_BUILD_WGET_OPTS pass extra options to the respective downloader. RUBY_BUILD_MIRROR_URL sets a custom mirror URL root.

That mirror variable is worth pausing on. If your network cannot reach the default download location, or if you build in an environment where outbound requests go through an internal mirror, RUBY_BUILD_MIRROR_URL plus a populated RUBY_BUILD_CACHE_PATH is the documented way to make builds reproducible. The README does not describe a rollback procedure for a partially completed install, so treat a failed build as something to clean up by removing the destination directory yourself.

ruby-build against ruby-install and rbenv

The README names ruby-install explicitly as the alternative for one specific reason: ruby-install consults remote resources to download the list of latest Ruby versions, so it does not need upgrading before it can install a newly released Ruby. ruby-build bundles its definitions instead, which makes it predictable and offline-friendly but means the tool and the version list move together. That is the real difference in approach, and it is a trade-off rather than a defect. If you pin Ruby versions in a lockfile and upgrade your tooling on a schedule, bundled definitions cost you nothing. If you install whatever shipped this week, they cost you a tool upgrade each time.

The comparison with rbenv is different in kind, because they are not competitors. The README describes ruby-build as available as a plugin for rbenv, where it provides the rbenv install command. rbenv handles version selection and shims; ruby-build handles the download and compile. The repository topics list rbenv-plugin alongside ruby, version-manager and hacktoberfest, which reflects that relationship. Running ruby-build standalone is a legitimate choice, but then nothing manages which installed Ruby your shell resolves to.

Maintenance, releases and what the MIT licence leaves to you

The repository is not archived, and the last push was on 2026-09-23. Releases are frequent and dated: v20260917, v20260916 and v20260915 all landed within three days of each other in September 2026. The dated release scheme is the practical signal here. Because definitions are bundled, a release is often just an updated set of definition files, which is why they arrive in bursts around Ruby point releases.

That frequency sets your upgrade cost. To install a Ruby version newer than your copy knows about, you upgrade ruby-build itself: brew upgrade ruby-build, a git pull in the plugin directory, or a fresh tarball for a manual install. There is no separate definition update channel documented in the README.

The project is MIT licensed, with the LICENSE file at the top level of the repository. MIT is permissive: it allows use, modification and redistribution with the licence and copyright notice retained. It does not cover the licences of the Ruby implementations ruby-build downloads, and those are separate works with their own terms. Nothing here is legal advice; if you redistribute a build product, check the licence of the implementation you compiled.

On the build side, the Makefile shows two targets. install runs bash install.sh, and the man page target regenerates share/man/man1/%.1 from .adoc sources using asciidoctor, installing it via gem if it is missing. If you build from a git checkout rather than a release tarball, that asciidoctor dependency is a real prerequisite for the documentation target, not for the install itself.

Editorial conclusion

Adopt ruby-build if you need a specific CRuby, JRuby, mruby, PicoRuby or TruffleRuby build in a prefix you control, and you already have compilers and development headers installed. Do not adopt it if you expect the tool to check those dependencies for you, or if you need it to discover Ruby releases the moment they ship; the README is explicit that new versions only appear after you upgrade ruby-build. Before rolling it out, confirm that your build environment has the libraries listed in the project's build-env documentation, and decide whether you want the standalone binary or the rbenv plugin, because the two place installed Rubies in different directories by default.

Frequently asked questions

Official sources

1. License: MIT
2. Project website
3. rbenv/ruby-build on GitHub
4. README
5. Releases