ruby-build cannot install a newly released Ruby until ruby-build itself is upgraded
A tool to download, compile, and install Ruby on Unix-like systems.
At a glance
- What is it?
- A source installer for six Ruby implementations whose version catalogue is a set of definition files committed to the repository, so freshness depends on upgrading the tool, and whose download client is whichever of three programs happens to be first on your PATH.
- Who is it for?
- ruby-build suits a team that wants reproducible, reviewable Ruby installs from source and accepts that a new Ruby release is not available until the tool is updated. Check five things before relying on it.
- Can I use it commercially?
- Yes. MIT is a permissive licence: you can use, modify and sell software built on it, as long as you keep its copyright and licence notices.
- Is it still maintained?
- Yes. The repository last received commits 10 days ago.
- What is it written in?
- Mainly Shell, according to GitHub's language statistics.
Answers come from the project's GitHub data, last synced on November 15, 2026, and from our analysis. They are not legal advice.
Star history
- rbenv/ruby-build3,988 ★ · +11
| Repository | 2026-09-24 | 2026-11-15 |
|---|---|---|
| rbenv/ruby-build | 4k | 4k |
11 Stars in the last 52 days, measured from the daily GitHub snapshot. Compare with other projects
Editorial analysis
A new Ruby is unreachable until the tool is upgraded
The most important thing to know about this project is stated plainly and then never mentioned again. When it lists latest versions, it only knows about the Ruby versions bundled with the project, and when a new Ruby comes out it will not know about it immediately. You have to upgrade ruby-build first. The reason given is structural: it bundles a definition file for each individual Ruby version, so a new Ruby is a new file that has to be written and shipped. That is a deliberate trade. A static catalogue is reviewable, works offline, and cannot change under you, and the cost is freshness. The file also names the alternative for anyone who disagrees, pointing at a different installer for readers whose requirement is that the tool always consults remote resources for the version list. The release record shows how that catalogue actually moves. The three newest tags are dated 20260924, 20260917 and 20260916, so versions are named by date rather than by sequence number, two of them landed on consecutive days, and the branch was pushed on 30 September, six days after the last tag.
The download client is whichever of three programs your PATH offers first
Downloading is configurable through a table of environment variables, and the first one worth reading is the client selector. It takes one of three values, and the default is the first of those three found on your PATH. So the tool that fetches your tarball is not chosen by the project, it is chosen by whatever happens to be installed on the machine, and two machines with different tooling will fetch differently. The next three variables pass extra options to each of the three clients respectively. Read together with the line above, the consequence is specific: if you set the options variable for one client and the machine resolves to a different one, your options are not an error, they are simply never used. The table also has a cache path whose default depends on how the tool was invoked, pointing at a directory under the rbenv root when it runs as a plugin and nowhere in particular otherwise, and a build path that defaults to a timestamped subdirectory of the temporary directory, which is what keeps two concurrent installs of different versions from colliding. The last row visible in the file names a mirror URL override, and its description cell is never closed off.
The tool checks its result and not its starting conditions
There is a warning callout near the top of the file and it is the only one. It says that ruby-build mostly does not verify that system dependencies are present before downloading and attempting to compile Ruby from source, and asks you to ensure that build tools and development headers are already installed. The hedge in mostly implies that some checking happens, and the file does not say which part. The step list immediately below it describes what the tool does, and the shape of that list is the point: download a tarball, extract to a temporary directory, run configure with a prefix, run make install, and then verify that the installed Ruby is functional. The post-condition is checked. The pre-conditions are not. So the failure modes of a missing dependency, a missing development header or an absent build tool do not surface as a friendly message before a download; they surface partway through a configure or compile step, after the source has already been fetched, and the message that appears will be the compiler's rather than the tool's. For a first install on a bare machine that ordering is the difference between a two-minute check and a twenty-minute one that ends in an error.
It will compile OpenSSL, and it prefers Homebrew's libraries where they exist
After describing the plain build steps, the file adds that depending on context the tool does a bit more, and gives two examples. The first is that it will try to link Ruby to the appropriate OpenSSL version, even if that means downloading and compiling OpenSSL itself. The second is that it will discover and link to Homebrew-installed instances of libraries such as libyaml and readline. Both are conveniences and both are reproducibility hazards, in the same direction. On a machine with Homebrew installed, the tool finds a library there and links against it in preference to whatever the system provides, silently. On a machine without Homebrew, it does not, and the system library is used or the build fails. So the same definition file, on the same definition of the same Ruby, produces two different binaries depending on what happens to be installed on the host. The OpenSSL case goes further, because the tool can become a nested build system: it can fetch, configure and compile a second project before it starts the first, which multiplies the time to install and gives you two build logs to read when something goes wrong.
Six implementations behind version prefixes, one of them named with a plus sign
Six Ruby implementations are supported, and the file selects between them by prefix rather than by a separate option. CRuby is listed with no prefix at all, in plain three-part version form, and is also the one implementation given an alias: ruby-build will accept a ruby- prefix on CRuby versions for compatibility with other version managers, which is why the usage examples show the same install expressed twice, once as a bare version and once with that prefix. JRuby, mruby, picoruby and the two TruffleRuby distributions take their own prefixes. The two TruffleRuby entries are worth pausing on, because they are not a variant but a different distribution, one native and one on the Java virtual machine, and telling them apart requires a prefix containing a plus sign. Two of the six names also sit uncomfortably close together, with mruby described as a lightweight embeddable implementation for microcontrollers and picoruby as an alternative mruby implementation for one-chip controllers, so a reader who types the shorter name gets a different implementation. The prefix flag itself is overloaded too, taking a full version, an aliased version, or a partial version that resolves to the newest release in that series.
Three install routes and two upgrade commands
Installation is documented three ways, and the upgrade story is not symmetric across them. The package manager route is a single line, and upgrading is a single line. The rbenv plugin route clones the repository into a directory under the rbenv root:
git clone https://github.com/rbenv/ruby-build.git "$(rbenv root)"/plugins/ruby-buildand upgrades with a pull in that same directory, which is a plain fetch and merge with no submodule handling shown. The third route is the one without a documented upgrade. It asks you to download a tarball from the project's releases page, then extract it and run its installer with a prefix set:
tar -xzf ruby-build-*.tar.gz
PREFIX=/usr/local ./ruby-build-*/install.shTwo costs there. The prefix in the example is a system location, so the common case needs write access to a directory most users cannot write without help. And the extraction has no destination, so it unpacks into whatever directory you happen to be standing in, and the two commands rely on a wildcard to find what the first one produced. There is no upgrade line for this route anywhere in the file, so a standalone user is left to work out whether re-running the installer over an existing copy is safe.
The Makefile finds the version by grepping a shell script and installs a gem to build the man page
The build file is four rules and contains two things worth knowing. The first is how it learns the version. It runs a shell pipeline that greps the main script for a line beginning with a version variable name and cuts that line on a double quote character. So the single source of truth for the version is one line inside a shell script, and the build reads it by pattern-matching that line and assuming a particular quoting style. Change the line to single quotes, or reflow it, and the pipeline returns nothing: the build does not fail, it proceeds with an empty version. The same variable is passed to the man page generator with a substitution that strips a leading v, which is why the release tags carry that prefix and the generated page does not. The second thing is how the man page gets built. The rule first checks whether a converter is present and, if it is not, installs it with a package manager for Ruby gems. So building a documentation page installs a gem into your Ruby installation, unpinned, and needs whatever write access your gem home requires. In fairness to this file, it does declare its one install target as phony, which is more than a number of comparable build files manage.
The custom definition example ends in a stray character and uses two placeholder versions
The advanced section is where the documentation thins, and the example there has two small defects. The first is its last line. After the four example commands, the block contains one more line whose entire content is a single backtick character, sitting inside the code block immediately before the fence that closes it. It is not a command, it is not a comment, and anyone copying the block copies a line that does nothing. The second defect is in the version names. The two ways of showing a custom definition use different placeholders: one uses a custom name in the 3.4 series and the other uses one in the 3.5 series, while the basic usage examples earlier in the file install a specific 3.4 release. So the 3.5 placeholder is a version ahead of anything the file claims is current, which is a small signal that these example lines were written at different times and never reconciled. The section also mixes the two interfaces in one block, four commands covering both the standalone program and the plugin, which is helpful for comparison and means the block cannot be run as a sequence without editing.
Editorial conclusion
ruby-build suits a team that wants reproducible, reviewable Ruby installs from source and accepts that a new Ruby release is not available until the tool is updated. Check five things before relying on it. The version list is bundled data, not a remote query, so a new Ruby means an upgrade of this tool first, and the file names an alternative for anyone who needs a live list. System dependencies are not checked before the download, so a missing header surfaces during configure or make. The download client is picked from your PATH, which means extra download options written for one client are ignored if a different one is installed. It may compile OpenSSL itself and will prefer Homebrew's libraries where they exist, so two machines can produce different binaries from one definition. And the tarball install route has no documented upgrade path.
Frequently asked questions
what is ruby build
A command-line tool that downloads, compiles and installs any Ruby version from source on Unix-like systems. It is available as a plugin for rbenv, where it provides the rbenv install command, or as a standalone program named ruby-build.
how to install ruby build
Three documented routes: brew install ruby-build, a git clone into the plugins directory under the rbenv root, or downloading a release tarball, extracting it and running its installer with a prefix. The first two have documented upgrade commands and the standalone tarball route does not.
Why can ruby-build not install a newly released Ruby?
Because it bundles a definition file for each individual Ruby version, so a new Ruby is a new file that has to be written and shipped. You have to upgrade ruby-build before the new version is installable, and the file points at a different installer for anyone who needs a tool that always consults remote resources.
Does ruby-build check system dependencies before compiling?
Mostly not. The file carries a warning that it does not verify that system dependencies are present before downloading and attempting to compile, and asks that build tools and development headers already be installed. What it does verify is the outcome, confirming that the installed Ruby is functional.
Which Ruby implementations can ruby-build install?
CRuby, listed as an unprefixed three-part version, plus JRuby, mruby, picoruby, truffleruby for the native standalone distribution and truffleruby+graalvm for the distribution on the Java virtual machine. CRuby also accepts a ruby- prefix for compatibility with other version managers.
How does ruby-build decide which download tool to use?
It takes one of aria2c, curl or wget, defaulting to whichever is first on your PATH. Separate environment variables pass extra options to each of the three, so options written for one client are not used if a different client is the one installed.
Official sources
Add this badge to your README
If you maintain this project, the badge below links readers to this analysis and shows its maintenance status from the daily GitHub snapshot. Paste the markdown into your README; add ?metric=license or ?metric=stars to the image URL for a different field.
[](https://hysenlabs.com/projects/rbenv-ruby-build)Star history chart for your README
[](https://hysenlabs.com/projects/rbenv-ruby-build)Was this useful?